<HTML>
<HEAD>
<TITLE> E-Kernel Required Reading </TITLE>
</HEAD>

<BODY style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">

<A NAME="top"></A>

<TABLE STYLE="text-align: left; margin-left: auto; margin-right: auto; width: 800px;" BORDER="0" CELLPADDING="5" CELLSPACING="2">
<TBODY>
<TR>
  <TD STYLE="background-color: rgb(153, 153, 153); vertical-align: middle; text-align: center;">
  <DIV ALIGN="right">
    <SMALL><SMALL><A HREF="index.html">Index Page</A></SMALL></SMALL>
  </DIV>
  <B>E-Kernel Required Reading</B> </TD>
</TR>
<TR>
  <TD STYLE="vertical-align: top;">

<H2> Table of Contents
</H2>

<PRE>
   <A HREF="#E-Kernel Required Reading">E-Kernel Required Reading</A>
      <A HREF="#Abstract">Abstract</A>
      <A HREF="#References">References</A>
      <A HREF="#Introduction">Introduction</A>
      <A HREF="#EK subsystem components">EK subsystem components</A>
         <A HREF="#EK science plan component">EK science plan component</A>
         <A HREF="#EK sequence component">EK sequence component</A>
      <A HREF="#EK experimenter's notebook component">EK experimenter's notebook component</A>
   <A HREF="#Sequence EK Concepts">Sequence EK Concepts</A>
      <A HREF="#Relational database functionality">Relational database functionality</A>
      <A HREF="#The sequence EK data model">The sequence EK data model</A>
         <A HREF="#Tables">Tables</A>
         <A HREF="#Column attributes">Column attributes</A>
      <A HREF="#The EK query language">The EK query language</A>
         <A HREF="#Query syntax">Query syntax</A>
         <A HREF="#The SELECT clause">The SELECT clause</A>
         <A HREF="#The FROM clause">The FROM clause</A>
         <A HREF="#The WHERE clause">The WHERE clause</A>
         <A HREF="#The ORDER BY Clause">The ORDER BY Clause</A>
         <A HREF="#Case sensitivity">Case sensitivity</A>
         <A HREF="#White space">White space</A>
         <A HREF="#Numeric values">Numeric values</A>
         <A HREF="#String values">String values</A>
         <A HREF="#Time values">Time values</A>
         <A HREF="#Null values">Null values</A>
         <A HREF="#Reserved Words">Reserved Words</A>
         <A HREF="#Query grammar">Query grammar</A>
         <A HREF="#Examples of syntactically valid queries">Examples of syntactically valid queries</A>
         <A HREF="#Examples of syntactically invalid queries">Examples of syntactically invalid queries</A>
         <A HREF="#Examples of semantically invalid queries">Examples of semantically invalid queries</A>
      <A HREF="#Sequence EK Files">Sequence EK Files</A>
         <A HREF="#Segments">Segments</A>
         <A HREF="#The comment area">The comment area</A>
      <A HREF="#Sequence EK tools">Sequence EK tools</A>
         <A HREF="#INSPEKT">INSPEKT</A>
         <A HREF="#COMMNT">COMMNT</A>
         <A HREF="#TOXFR and TOBIN">TOXFR and TOBIN</A>
         <A HREF="#SPACIT">SPACIT</A>
   <A HREF="#Reading sequence EKs">Reading sequence EKs</A>
      <A HREF="#Loading and unloading sequence EKs">Loading and unloading sequence EKs</A>
      <A HREF="#Query-and-fetch interface">Query-and-fetch interface</A>
         <A HREF="#Issuing queries">Issuing queries</A>
         <A HREF="#Fetching data from matching rows">Fetching data from matching rows</A>
         <A HREF="#Query support utilities">Query support utilities</A>
      <A HREF="#Record-oriented reader interface">Record-oriented reader interface</A>
         <A HREF="#Opening files for record-oriented reading">Opening files for record-oriented reading</A>
         <A HREF="#Column entry readers">Column entry readers</A>
      <A HREF="#Informational functions">Informational functions</A>
         <A HREF="#Summarizing EK files">Summarizing EK files</A>
         <A HREF="#Summarizing loaded tables">Summarizing loaded tables</A>
   <A HREF="#Writing sequence EKs">Writing sequence EKs</A>
      <A HREF="#Introduction0">Introduction</A>
      <A HREF="#Opening a sequence EK for writing">Opening a sequence EK for writing</A>
         <A HREF="#Beginning a new sequence EK">Beginning a new sequence EK</A>
         <A HREF="#Opening an existing sequence EK for writing">Opening an existing sequence EK for writing</A>
      <A HREF="#Choosing a writing method">Choosing a writing method</A>
         <A HREF="#Specifying segment attributes">Specifying segment attributes</A>
         <A HREF="#Table and column names">Table and column names</A>
         <A HREF="#Column declarations">Column declarations</A>
         <A HREF="#Consistency of schemas">Consistency of schemas</A>
      <A HREF="#Using the record-oriented sequence EK writers">Using the record-oriented sequence EK writers</A>
         <A HREF="#Beginning a segment">Beginning a segment</A>
         <A HREF="#Adding records to a segment">Adding records to a segment</A>
      <A HREF="#Using the fast writers">Using the fast writers</A>
         <A HREF="#Initiating a fast write">Initiating a fast write</A>
         <A HREF="#Adding columns to the segment">Adding columns to the segment</A>
         <A HREF="#Completing a fast write">Completing a fast write</A>
         <A HREF="#Restrictions">Restrictions</A>
      <A HREF="#Updating an existing sequence EK">Updating an existing sequence EK</A>
      <A HREF="#Closing a sequence EK">Closing a sequence EK</A>
   <A HREF="#Appendix A --- Summary of E-kernel Functions">Appendix A --- Summary of E-kernel Functions</A>
      <A HREF="#Summary of mnemonics">Summary of mnemonics</A>
      <A HREF="#Summary of Calling Sequences">Summary of Calling Sequences</A>
      <A HREF="#Revisions">Revisions</A>
         <A HREF="#February 24, 2010 EDW (JPL)">February 24, 2010 EDW (JPL)</A>
         <A HREF="#April 1, 2009">April 1, 2009</A>
         <A HREF="#Feb. 06, 2002">Feb. 06, 2002</A>
         <A HREF="#Jan. 15, 2002">Jan. 15, 2002</A>

</PRE>

<HR SIZE=3 NOSHADE>

<BR><BR>
<A NAME="E-Kernel Required Reading"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> E-Kernel Required Reading
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   Last revised on 2010 APR 07 by E. D. Wright.
<P>
 
<BR><BR>
<A NAME="Abstract"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Abstract
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The SPICE events subsystem and Events Kernel (EK) are used to implement
   the sequence component of the Events Kernel (EK/ESQ), and may be used in
   any other application where a modest SQL-like database is called for.
<P>
 
<BR><BR>
<A NAME="References"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> References
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   NAIF document numbers are shown preceding document titles.
<P>
 
<UL>
<TT>1.</TT> [218] KERNEL Required Reading (<a href="../req/kernel.html">kernel.req</a>)
<BR><BR></UL>
<UL>
<TT>2.</TT> [222] SCLK Required Reading (<a href="../req/sclk.html">sclk.req</a>)
<BR><BR></UL>
<UL>
<TT>3.</TT> [225] TIME Required Reading (<a href="../req/time.html">time.req</a>)
<BR><BR></UL>
<UL>
<TT>4.</TT> [278] COMMNT User's Guide (<a href="../ug/commnt.html">commnt.ug</a>)
<BR><BR></UL>
<UL>
<TT>5.</TT> [284] INSPEKT User's Guide (<a href="../ug/inspekt.html">inspekt.ug</a>)
<BR><BR></UL>
<UL>
<TT>6.</TT> [286] DAS Required Reading (<a href="../req/das.html">das.req</a>)
<BR><BR></UL>
<UL>
<TT>7.</TT> [333] Converting and Porting SPICE Data Files (<a href="../ug/convert.html">convert.ug</a>)
<BR><BR></UL>
<UL>
<TT>8.</TT> [A] (No NAIF document number available) SPICE Tutorial chapter: ``Events
Kernel Notebook Component ENB''
<BR><BR></UL>
<BR><BR>
<A NAME="Introduction"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Introduction
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The E-kernel (``EK'') is the logical component of the SPICE system that
   deals with ``event'' data. In the context of space science missions,
   event data may be interpreted as the collection of information
   concerning planned or unplanned mission activities or occurrences that
   can assist in extracting the full value of the science data returned
   from those missions. Event data may also include data used to assist
   mission operations. The definition of event data given here is
   deliberately broad; selection of appropriate event data must be carried
   out on an application-by-application basis. Examples of event data
   include, but are not limited to, statements of scientific objectives,
   planned or actual sequences of commands executed onboard spacecraft, and
   notebook or log entries of scientists or mission operations personnel.
<P>
 
   The SPICE E-kernel (EK) subsystem is intended to support convenient
   recording, electronic transfer, archival, examination, and manipulation
   of event data by human users and software. Because the form, content,
   and quantity of event data may vary widely from one mission or
   application to next, the EK subsystem emphasizes flexibility in
   accommodating event data and imposes few restrictions on the types of
   data that can be included within the subsystem.
<P>
 
   The EK subsystem includes two separate software mechanisms for storing
   and handling event data. One of these is a simple, stand-alone
   relational database system. This system includes event data files, SPICE
   software that manipulates those files, and documentation. The data files
   used by this system are called ``sequence E-kernels,'' ``sequence EK
   files'' or ``sequence EKs''; often the qualifier ``sequence'' is
   omitted. SPICE EK software enables sequence EKs to be examined,
   interactively or through an application programming interface (API), by
   means of a simple, SQL-like query language. The sequence EK file format
   and associated software are discussed in detail below.
<P>
 
   The second mechanism is an e-mail and web-based software system that
   allows users to archive and share text notes and e-mail messages, the
   latter of which may optionally include MIME attachments. This is known
   as the ``experimenter's notebook'' or ``ENB'' system. The ENB system is
   documented in reference [A].
<P>
 
   While the EK subsystem allows users to package an almost limitless
   variety of event data, the subsystem is designed to support in
   particular three of the categories of data listed above:
<P>
 
<UL>
<TT>--</TT> Statements of scientific objectives
<BR><BR></UL>
<UL>
<TT>--</TT> Sequences of spacecraft commands
<BR><BR></UL>
<UL>
<TT>--</TT> Notebook or log entries
<BR><BR></UL>
   The EK subsystem is partitioned into three ``components,'' each one
   designed to accommodate one of the types of data listed above. The names
   of these components are, respectively,
<P>
 
<UL>
<TT>--</TT> The Science Plan
<BR><BR></UL>
<UL>
<TT>--</TT> The Sequence Component
<BR><BR></UL>
<UL>
<TT>--</TT> The Experimenter's Notebook (``ENB'')
<BR><BR></UL>
<BR><BR>
<A NAME="EK subsystem components"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> EK subsystem components
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Below, we present a high-level description of the components of the EK
   subsystem and suggested applications of these components.
<P>
 
<BR><BR>
<A NAME="EK science plan component"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> EK science plan component
</H3><P><BR><BR>
   The purpose of the Science Plan component of the SPICE EK subsystem is
   to record high-level descriptions of planned mission activities,
   particularly, but not necessarily limited to, those pertaining to
   science experiments. Science plan entries should enable the reader to
   understand the objectives of mission activities, and where appropriate,
   should give a high-level description of how they are carried out. A
   description of a mosaic of optical photographs might belong in the
   science plan; the commands used to execute the mosaic probably would be
   best relegated to the EK sequence component, which is described below.
<P>
 
   Depending on mission requirements, either the ENB or Sequence EK system
   may be suitable for storing Science Plan data.
<P>
 
<BR><BR>
<A NAME="EK sequence component"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> EK sequence component
</H3><P><BR><BR>
   The sequence component of the SPICE EK subsystem is intended to deal
   with event data that fit the relational database paradigm: specifically,
   data that can be meaningfully and advantageously represented as a series
   of tables, each one of which is characterized by a collection of rows
   and columns. This type of organization is likely appropriate when:
<P>
 
<UL>
<TT>--</TT> The structure of the data is regular
<BR><BR></UL>
<UL>
<TT>--</TT> The volume of the data is large
<BR><BR></UL>
<UL>
<TT>--</TT> The capability of searching the data rapidly, preferably in random-access
fashion, for items of interest is required
<BR><BR></UL>
<UL>
<TT>--</TT> The capability of specifying relational search constraints is required
<BR><BR></UL>
<UL>
<TT>--</TT> The data must be accessible by software as well as by human readers
<BR><BR></UL>
   This last criterion may apply even when the primary means of access to
   the data is visual inspection, if the data volume is large enough:
   software may be required to enable users to select manageable subsets of
   the data to browse on-line or in the form of printed listings.
<P>
 
   Data stored in the sequence component of the EK subsystem might
   represent sequences of time-tagged ``events.'' Sequences of commands
   sent to a spacecraft are an example of such event data. Terse notes
   indicating occurrences of geometric events such as equator crossings or
   times of closest approach of a spacecraft relative to a target are
   another example of suitable data to include in this component.
<P>
 
   When event data consist of or include descriptions of state changes of
   systems of interest, a sequence EK containing these data could be used
   to find the states of the corresponding systems at a given time.
<P>
 
   The data comprising an event may correspond to a row in a table, and
   attributes of the event could be represented by entries in different
   columns within the row. A trivial, fictitious example of this sort of
   logical organization is shown in the table below:
<P>
 
<PRE>
             (column 1)   (column 2)           (column 3)
 
                TIME       MNEMONIC              EVENT
 
            +------------------------------------------------------+
   (row 1)  | 3987:64:2 | CMD,PWRON  |  Turn camera power on       |
            +------------------------------------------------------+
   (row 2)  | 3989:01:0 | CMD,FILCLR |  Select CLEAR filter        |
            +------------------------------------------------------+
   (row 3)  | 4000:01:5 | CMD,SHUTR  |  Shutter photo              |
            +------------------------------------------------------+
   (row 4)  | 4000:01:5 | COMMENT    |  OPNAV photo #1 complete    |
            +------------------------------------------------------+
       .                               .
       .                               .
       .                               .
 
</PRE>
   With regard to such a table, we might wish to construct queries such as:
<P>
 
<PRE>
   "Find the filter selection commands that occurred between
   spacecraft clock times 5000:23:0 and 5001:00:0"
 
   "Find the events containing the word ``camera'' and display them
   ordered by mnemonic"
 
   "Find the last event description starting with the string ``Turn''
   prior to the UTC time 1-JAN-1997 12:14:02"
 
   "Find the times of all the ``Shutter photo'' events"
</PRE>
   We might want to display the rows satisfying these queries on our
   terminals, dump them to a file, or use them to drive a program. All of
   these functions are supported by the sequence EK subsystem. Note that
   the queries shown above are English paraphrases of the equivalent
   expressions in the EK query language.
<P>
 
   The functional capabilities described above are provided by files and
   software capable of accessing those files. The EK API contains
   ``writer'' software that enables users to create sequence EK files that
   contain data organized in a tabular fashion. The data then can be
   accessed using ``reader'' functions from the EK API, or interactively
   using the EK browsing program INSPEKT.
<P>
 
   Sequence EK files are binary files and therefore cannot be read directly
   using text editing programs. However, the program INSPEKT can dump any
   selected portion of any sequence EK as a text file, using user-specified
   formats, so in a sense sequence EK files are more flexible than flat
   text files as a repository for event information. By using a
   database-style internal data representation rather than a
   format-oriented one, they avoid the constraints on their contents that
   would be imposed by adoption of fixed file formats.
<P>
 
   Sequence EK files may be ported between computer systems having
   different internal data formats; the SPICE Toolkit utilities TOBIN and
   TOXFR support this function.
<P>
 
   Sequence EK files may also have labels and free-form text inserted into
   them to assist in clear and complete identification of the files; the
   SPICE Toolkit utility COMMNT may be used for this purpose.
<P>
 
   A detailed discussion of the functional characteristics of the sequence
   component is given below in the chapter titled ``Sequence EK Concepts.''
<P>
 
<BR><BR>
<A NAME="EK experimenter's notebook component"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> EK experimenter's notebook component
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The experimenter's notebook component of the EK subsystem is primarily
   intended to be a mechanism for recording after-the-fact observations,
   particularly of anomalies or other unplanned events. Notes of general
   interest to scientists may also be appropriate.
<P>
 
   More generally, the experimenter's notebook component may include any EK
   data that don't fit into the other two components. For example, if the
   available, human-readable command sequence data are extremely small in
   volume, it may be more practical to include them in the experimenter's
   notebook than to insert them into a binary sequence EK.
<P>
 
<BR><BR>
<A NAME="Sequence EK Concepts"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Sequence EK Concepts
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<BR><BR>
<A NAME="Relational database functionality"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Relational database functionality
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The sequence EK subsystem is a simple, stand-alone relational database
   system, with a few modifications to better adapt the system to
   EK-specific applications.
<P>
 
   The sequence EK subsystem provides an application programming interface
   (API) for creating, modifying, reading, summarizing, and annotating
   sequence EK files. In particular, the API supports reading using a
   query-and-fetch mechanism: an application passes a request for data
   called a ``query'' to the EK subsystem, then retrieves the data using a
   suite of API routines. Queries are expressed in a simple language that
   closely resembles the standard relational database query language SQL.
<P>
 
   The sequence EK query capability is also provided using the CSPICE
   interactive browsing utility INSPEKT. However, INSPEKT does not support
   any sequence EK writing functionality.
<P>
 
   The functionality of sequence EK software is almost completely
   independent of its intended application as a system for handling event
   data. One could think of the software system not as an ``event kernel''
   but simply as a ``database kernel,'' and in fact the term ``database
   kernel'' and the acronym ``DBK'' have been used in some CSPICE
   documentation. However, since the ``EK'' prefix has already been widely
   used in naming functions belonging to the EK API, we'll stick with the
   name ``EK'' in our discussion.
<P>
 
<BR><BR>
<A NAME="The sequence EK data model"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> The sequence EK data model
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Below we discuss the logical organization of data in the sequence EK
   subsystem.
<P>
 
<BR><BR>
<A NAME="Tables"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Tables
</H3><P><BR><BR>
   A sequence EK database is logically a set of tables. Each table is made
   up of rows and columns. Tables are ``rectangular'': there is the same
   number of rows in each column. The intersection of a row and column is
   called a ``column entry.'' All columns within a table have the same
   number of entries---one per row.
<P>
 
   The sequence EK data model diverges slightly from the relational model
   in that columns are allowed to have arrays as entries. We call such
   columns ``array-valued'' or ``vector-valued.'' When a column entry is an
   array, we call the components of the array ``column entry elements'' or
   ``elements'' if the context is clear.
<P>
 
<BR><BR>
<A NAME="Column attributes"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Column attributes
</H3><P><BR><BR>
   Each column has a number of attributes that characterize the data it
   contains. These attributes apply uniformly to the entries within a
   column:
<P>
 
<UL>
<TT>--</TT> Data type
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Column entries may have INTEGER, CHARACTER, DOUBLE PRECISION, or TIME data
type.
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> The TIME data type is used to represent epochs. As such, the TIME type
plays the same role as the DATE datatype in the SQL language.
<BR><BR></UL>
<UL>
<TT>--</TT> Dimension
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Column entries may have fixed or variable dimension. When a column has
fixed-dimension entries of size 1, the column is said to be
``scalar-valued.'' Otherwise, the column is said to be ``array valued,''
``vector valued,'' or, if the dimension is variable, ``variable-sized.''
There is no limit imposed by the EK subsystem on the dimension of a
column's entries.
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Array-valued columns may not be referenced in query constraints.
<BR><BR></UL>
<UL>
<TT>--</TT> String length (applies only to character columns)
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Array-valued columns having entries of CHARACTER type have a fixed, maximum
string length associated with them. Scalar-valued CHARACTER columns may
have variable-length strings as entries. For all CHARACTER columns, the
maximum allowed string length is 1024 characters.
<BR><BR></UL>
<UL>
<TT>--</TT> Whether null values are allowed
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> At the time an EK segment is created, each column declaration indicates
whether the column may contain null values. In columns that allow null
entries, entries may be designated as null when segments are written.
<BR><BR></UL>
<BR><BR>
<A NAME="The EK query language"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> The EK query language
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
<BR><BR>
<A NAME="Query syntax"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Query syntax
</H3><P><BR><BR>
   An EK query is a character string that specifies a set of EK data to
   select from those present in currently loaded EK files. A query
   specifies columns and tables of interest, and optionally specifies
   constraints that entries in the tables' rows must match. We refer to
   rows that satisfy the constraints as ``matching rows.''
<P>
 
   The selected data will be retrievable using the EK fetch routines
   <a href="../cspice/ekgc_c.html">ekgc_c</a>, <a href="../cspice/ekgd_c.html">ekgd_c</a>, and <a href="../cspice/ekgi_c.html">ekgi_c</a>.
<P>
 
   The query consists of four clauses, the third and fourth of which are
   optional. The general form of a query is
<P>
 
<PRE>
   SELECT &lt;column list&gt;
   FROM &lt;table list&gt;
   [WHERE &lt;constraint list&gt;]
   [ORDER BY &lt;ORDER BY column list&gt;]
</PRE>
   where brackets indicate optional items. The elements of the query shown
   above are called, respectively, the ``SELECT clause,'' the ``FROM
   clause,'' the ``WHERE clause,'' and the ``ORDER BY clause.'' The result
   of a query may be thought of as a new table, whose columns are those
   specified in the SELECT clause and whose rows are those satisfying the
   constraints of the WHERE clause, ordered according to the ORDER BY
   clause.
<P>
 
<BR><BR>
<A NAME="The SELECT clause"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The SELECT clause
</H3><P><BR><BR>
   The SELECT clause specifies a list of columns from which to select data.
   In a simple (non-join) query, these columns must belong to the single
   table specified in the FROM clause.
<P>
 
   The form of a SELECT clause is
<P>
 
<PRE>
   SELECT &lt;column name&gt; [ , &lt;column name&gt;...]
</PRE>
   In queries having multiple tables in the FROM clause (see below), column
   names are ambiguous if they occur in more than one table in the FROM
   clause. Such column names must be qualified with table identifiers.
   These identifiers may be the names of the tables to which the columns
   belong, or table ``aliases,'' names (usually short ones) associated with
   tables in the FROM clause. Table aliases have duration limited to the
   execution of the query to which they belong.
<P>
 
   The form of a qualified column name is
<P>
 
<PRE>
   &lt;table name&gt;.&lt;column name&gt;
</PRE>
   or
<P>
 
<PRE>
   &lt;table alias&gt;.&lt;column name&gt;
</PRE>
   Columns named in the SELECT clause must be present in some loaded EK for
   the query to be semantically valid.
<P>
 
<BR><BR>
<A NAME="The FROM clause"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The FROM clause
</H3><P><BR><BR>
   The FROM clause specifies the tables from which to select data. In
   simple queries, only one table is listed. In this case the form of the
   FROM clause is
<P>
 
<PRE>
   FROM &lt;table name&gt;
</PRE>
   In queries involving multiple tables, the form of the FROM clause
   becomes
<P>
 
<PRE>
   FROM &lt;table name&gt; [&lt;table alias&gt;]
        [ , &lt;table name&gt; [&lt;table alias&gt;] ... ]
</PRE>
   The aliases associated with the table names must be distinct and must
   not be the actual names of loaded EK tables.
<P>
 
   Queries involving multiple tables are called ``joins.''
<P>
 
   The meaning of a FROM clause containing multiple tables is that the
   output is to be a subset of the rows of the Cartesian product of the
   listed tables. Normally, WHERE clause constraints are supplied to reduce
   the selected rows to a set of interest.
<P>
 
   The most common example of a join is a query with two tables listed in
   the FROM clause, and a WHERE clause constraint enforcing equality of
   members of a column in the first table with members of column in the
   second table. Such a query is called an ``equi-join.'' A join in which
   columns of different tables are related by an inequality is called a
   ``non-equi-join.'' Any type of join other than an equi-join may be very
   slow to evaluate, due to the large number of elements that may be
   contained in the Cartesian product of the listed tables.
<P>
 
<BR><BR>
<A NAME="The WHERE clause"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The WHERE clause
</H3><P><BR><BR>
   The WHERE clause lists constraints that must be met by each row
   satisfying the query. The constraints are specified as a logical
   combination of relational expressions. The form of the constraint list
   is
<P>
 
<PRE>
   WHERE &lt;constraint expression&gt;
</PRE>
   where each &lt;constraint expression&gt; consists of one or more simple
   relational expressions of the form
<P>
 
<PRE>
   &lt;column name&gt; &lt;operator&gt; &lt;RHS symbol&gt;
</PRE>
   Here
<P>
 
<PRE>
   &lt;RHS symbol&gt;
</PRE>
   is a column name, a literal value, or the special symbol
<P>
 
<PRE>
   NULL
</PRE>
   and
<P>
 
<PRE>
   &lt;operator&gt;
</PRE>
   is any of
<P>
 
<PRE>
   EQ, GE, GT, LE, LIKE, LT, NE, NOT LIKE, &lt;, &lt;=, =, &gt;, &gt;=, !=, &lt;&gt;
</PRE>
   For comparison with null values, the special expressions
<P>
 
<PRE>
   &lt;column name&gt; IS NULL
   &lt;column name&gt; IS NOT NULL
</PRE>
   are allowed.
<P>
 
   The LIKE operator allows comparison of a string value against a
   template. The template syntax is that allowed by the CSPICE routine
   MATCHI. Templates may include literal characters, the wild string marker
   '*', and the wild character marker '%'. Case is significant in
   templates.
<P>
 
   Templates are bracketed by quote characters, just as are literal
   strings.
<P>
 
   The query language also supports the BETWEEN and NOT BETWEEN constructs
<P>
 
<PRE>
   &lt;column&gt; BETWEEN &lt;symbol 1&gt; AND &lt;symbol 2&gt;
 
   &lt;column&gt; NOT BETWEEN &lt;symbol 1&gt; AND &lt;symbol 2&gt;
</PRE>
   The tokens
<P>
 
<PRE>
   &lt;symbol 1&gt;
   &lt;symbol 2&gt;
</PRE>
   may be literal values or column names.
<P>
 
   The BETWEEN operator considers values that match the bounds to satisfy
   the condition: the BETWEEN operator tests for inclusion in the closed
   interval defined by the bounds.
<P>
 
   The order of the bounds doesn't matter: the bounds are considered to
   define the interval from the smaller bound to the larger.
<P>
 
   In the WHERE clause, simple relational expressions may be combined using
   the logical operators AND, OR, and NOT, as in the Fortran programming
   language. Parentheses may be used to enforce a desired order of
   evaluation of logical expressions.
<P>
 
   The expression syntax is NOT symmetric: literal values must not appear
   on the left hand side of the operators that apply to them.
<P>
 
   Data types of the columns or constants used on the right-hand-sides of
   operators must match the data types of the corresponding columns on the
   left-hand-sides, except that comparison of integer and double precision
   quantities is permitted.
<P>
 
   The columns named in a WHERE clause must belong to the tables listed in
   the FROM clause. If the query is a join, qualifying table names or
   aliases are required wherever their omission would result in ambiguity.
<P>
 
   Columns referenced in a WHERE clause must be scalar-valued.
<P>
 
<BR><BR>
<A NAME="The ORDER BY Clause"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The ORDER BY Clause
</H3><P><BR><BR>
   The ``ORDER BY'' clause indicates which columns to use to order the
   output generated by the query. The columns in the order-by clause define
   a dictionary ordering, with the first listed column acting as a primary
   key, the second column acting as a secondary key, and so on.
<P>
 
   For each ORDER BY column, the keywords ASC or DESC may be supplied to
   indicate whether the items in that column are to be listed in ascending
   or descending order. Ascending order is the default. The direction in
   which data items increase is referred to as the ``order sense.''
<P>
 
   The ORDER BY clause, if present, must appear last in the query.
<P>
 
   The form of the ORDER BY clause is
<P>
 
<PRE>
   ORDER BY &lt;column name&gt; [&lt;order sense&gt;]
            [ ,&lt;column name&gt; [&lt;order sense&gt;]...]
</PRE>
   Rows satisfying the query constraints will be returned so that the
   entries of the first column specified in the ORDER BY clause will appear
   in the order specified by the order sense keyword, which is assumed to
   be ASC if absent. When entries in the first through Nth ORDER BY column
   are equal, the entries in the (N+1)st ORDER BY column determine the
   order of the rows, and so on.
<P>
 
   As in the WHERE clause, ORDER BY column names must be qualified by table
   names or table aliases where they would otherwise be ambiguous.
<P>
 
   In order for a column to be eligible to be referenced in an ORDER BY
   clause, the column must scalar valued.
<P>
 
<BR><BR>
<A NAME="Case sensitivity"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Case sensitivity
</H3><P><BR><BR>
   Case is not significant in queries, except within literal strings. For
   these case sensitivity depends on the relational operators applied to
   the strings. All comparison operators other than the LIKE operator are
   case sensitive: for example, the strings
<P>
 
<PRE>
   "And"
</PRE>
   and
<P>
 
<PRE>
   "and"
</PRE>
   are not considered to be equal. On the other hand, the expression
<P>
 
<PRE>
   ANIMAL LIKE "*A*"
</PRE>
   would be considered true when ANIMAL takes the value
<P>
 
<PRE>
   "cat"
</PRE>
   Case is not significant in time values.
<P>
 
<BR><BR>
<A NAME="White space"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> White space
</H3><P><BR><BR>
   The blank is the only character considered to be a white space character
   in the EK query syntax. In particular, tabs are not treated as white
   space characters.
<P>
 
   Within string constants, leading or embedded white space is significant.
   Elsewhere, any string of one or more consecutive blanks is interpreted
   as a single blank.
<P>
 
   White space is required to separate alphanumeric tokens, such as
<P>
 
<PRE>
   SELECT
</PRE>
   and
<P>
 
<PRE>
    LT
</PRE>
   White space may be omitted between special characters and alphanumeric
   tokens, such as
<P>
 
<PRE>
   )
</PRE>
   and
<P>
 
<PRE>
   WHERE
</PRE>
<BR><BR>
<A NAME="Numeric values"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Numeric values
</H3><P><BR><BR>
   Any numeric format accepted by the CSPICE routine <a href="../cspice/prsdp_c.html">prsdp_c</a> may be used to
   represent numeric values in relational expressions.
<P>
 
   The equality operator EQ indicates a test for exact equality. Care must
   be taken in testing double precision column entries for equality with a
   specified value; round-off errors may cause such tests to fail
   unexpectedly.
<P>
 
<BR><BR>
<A NAME="String values"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> String values
</H3><P><BR><BR>
   Literal strings used in the right hand side of relational expressions,
   such as the string
<P>
 
<PRE>
   SSI_EVENT
</PRE>
   in the query
<P>
 
<PRE>
   * where event_type eq "SSI_EVENT"
</PRE>
   are always bracketed by quotation marks. Either single or double quotes
   may be used, as long as the string is started and terminated with the
   same character. Within character string values, quote characters must be
   doubled in order to be recognized.
<P>
 
<BR><BR>
<A NAME="Time values"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Time values
</H3><P><BR><BR>
   Time values are considered to be strings and require bracketing quotes.
   Either single or double quotes are allowed, as long as the quote
   characters match. The allowed time values are strings accepted by the
   CSPICE routine <a href="../cspice/str2et_c.html">str2et_c</a>, and SCLK strings in SPICE format.
<P>
 
   When SCLK strings are used, they must be prefixed by a substring
   indicating the name of the clock, followed by the token SCLK. For
   example:
<P>
 
<PRE>
   MGS SCLK 2400001.125
</PRE>
   Time values specified in queries are always converted to barycentric
   dynamical time (TDB) before comparisons with column entries are
   performed. Therefore, programs using the EK subsystem should load a
   leapseconds kernel and any appropriate SCLK kernels before attempting to
   issue queries involving time values to the EK subsystem. See [222] and
   [225] for further information on time conversions.
<P>
 
   As with double precision values, time values cannot generally be
   reliably tested for exact equality with column entries. It's usually
   better to test whether a time column entry is in a desired range than to
   test whether it's equal to a specific value.
<P>
 
<BR><BR>
<A NAME="Null values"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Null values
</H3><P><BR><BR>
   The symbol
<P>
 
<PRE>
   NULL
</PRE>
   may be used on the right-hand-side of relational expression in which the
   column named on the left-hand of the expression allows null values, when
   the relational operators are either of
<P>
 
<PRE>
   IS NULL
   IS NOT NULL
</PRE>
   The case of the letters in the symbol ``NULL'' is not significant. The
   symbol is written without quotes.
<P>
 
<BR><BR>
<A NAME="Reserved Words"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Reserved Words
</H3><P><BR><BR>
   The query language contains the following reserved words:
<P>
 
<PRE>
   ALL
   AND
   ASC
   AVG
   BETWEEN
   BY
   COUNT
   DESC
   DISTINCT
   EQ
   FROM
   GE
   GROUP
   GT
   HAVING
   IS
   LE
   LIKE
   LT
   MAX
   MIN
   NE
   NOT
   NULL
   OR
   ORDER
   SELECT
   SUM
   WHERE
</PRE>
   Some of the above are not currently used but are reserved for upward
   compatibility.
<P>
 
   Reserved words must be separated from other words in queries by white
   space.
<P>
 
<BR><BR>
<A NAME="Query grammar"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Query grammar
</H3><P><BR><BR>
   A BNF representation of the sequence EK query grammar is as shown:
<P>
 
<PRE>
   &lt;QUERY&gt;                 =&gt;    &lt;SELECT clause&gt; &lt;FROM clause&gt;
                                 &lt;WHERE clause&gt; &lt;ORDER BY clause&gt;
 
   &lt;SELECT clause&gt;         =&gt;    SELECT &lt;select list&gt;
 
   &lt;select list&gt;           =&gt;    &lt;column entry&gt;
                               | &lt;select list&gt;, &lt;column entry&gt;
 
   &lt;column entry&gt;          =&gt;    &lt;table name&gt;.&lt;column name&gt;
                               | &lt;column name&gt;
 
   &lt;FROM clause&gt;           =&gt;    FROM &lt;table name list&gt;
 
   &lt;table name list&gt;       =&gt;    &lt;table entry&gt;
                               | &lt;table name list&gt;, &lt;table entry&gt;
 
   &lt;table entry&gt;           =&gt;    &lt;table name&gt;
                               | &lt;table name&gt; &lt;table alias&gt;
 
   &lt;WHERE clause&gt;          =&gt;    WHERE &lt;relational expression&gt;
                               | &lt;NIL&gt;
 
 
   &lt;relational expression&gt;  =&gt;   &lt;simple expression&gt;
 
                               | &lt;NULL value expression&gt;
 
                               | NOT &lt;relational expression&gt;
 
                               |   ( &lt;relational expression&gt; )
 
                               |     &lt;relational expression&gt;
                                 AND &lt;relational expression&gt;
 
                               |     &lt;relational expression&gt;
                                 OR  &lt;relational expression&gt;
 
 
   &lt;simple expression&gt;      =&gt;   &lt;LHS&gt; &lt;operator&gt; &lt;RHS&gt;
 
                               | &lt;LHS&gt; BETWEEN     &lt;RHS&gt; AND &lt;RHS&gt;
 
                               | &lt;LHS&gt; NOT BETWEEN &lt;RHS&gt; AND &lt;RHS&gt;
 
 
   &lt;NULL value expression&gt;  =&gt;   &lt;LHS&gt; &lt;Null operator&gt; NULL
 
 
   &lt;LHS&gt;                    =&gt;   &lt;name&gt;
 
 
   &lt;RHS&gt;                    =&gt;   &lt;name&gt;
                               | &lt;value&gt;
 
 
   &lt;name&gt;                   =&gt;   &lt;identifier&gt; . &lt;identifier&gt;
                               | &lt;identifier&gt;
 
 
   &lt;operator&gt;               =&gt;   EQ
                               | GE
                               | GT
                               | LE
                               | LT
                               | NE
                               | LIKE
                               | NOT LIKE
                               | =
                               | &gt;=
                               | &gt;
                               | &lt;=
                               | &lt;
                               | !=
                               | &lt;&gt;
 
 
   &lt;NULL operator&gt;         =&gt;    IS
                               | IS NOT
                               | EQ
                               | NE
                               | =
                               | !=
                               | &lt;&gt;
 
 
   &lt;value&gt;                 =&gt;    &lt;character value&gt;
                               | &lt;d.p. value&gt;
                               | &lt;integer value&gt;
 
 
   &lt;ORDER BY clause&gt;       =&gt;    ORDER BY &lt;order-by list&gt;
                               | &lt;NIL&gt;
 
   &lt;order-by list&gt;         =&gt;    &lt;order-by column entry&gt;
                               | &lt;order-by list&gt;,
                                 &lt;order-by column entry&gt;
 
   &lt;order-by column entry&gt; =&gt;    &lt;column entry&gt; &lt;order&gt;
                               | &lt;column entry&gt;
 
   &lt;order&gt;                 =&gt;    ASC
                               | DESC
</PRE>
<BR><BR>
<A NAME="Examples of syntactically valid queries"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Examples of syntactically valid queries
</H3><P><BR><BR>
   Below is a collection of examples of strings containing syntactically
   valid queries.
<P>
 
   The column names referenced in the queries are used as examples and are
   not meant to suggest that columns having those names will be present in
   any particular EKs.
<P>
 
<PRE>
   SELECT COL1 FROM TAB1
 
   select col1 from tab1 where col1 gt 5
 
   SELECT COL2 FROM TAB1 WHERE COL2 &gt; 5.7 ORDER BY COL2
 
   SELECT COL2 FROM TAB1 WHERE COL1 != 5
 
   SELECT COL2 FROM TAB1 WHERE COL1 GE COL2
 
   SELECT COL1, COL2, COL3 FROM TAB1 ORDER BY COL1
 
   SELECT COL3 FROM TAB1 WHERE COL5 EQ "ABC"
 
   SELECT COL3 FROM TAB1 WHERE COL5 = "ABC"
 
   SELECT COL3 FROM TAB1 WHERE COL5 LIKE 'A*'
 
   SELECT COL3 FROM TAB1 WHERE COL5 LIKE 'A%%'
 
   SELECT COL4 FROM TAB1 WHERE COL4 = '1995 JAN 1 12:38:09.7'
 
   SELECT COL4 FROM TAB1 WHERE COL4 = "1995 JAN 1 12:38:09.7"
 
   SELECT COL4 FROM TAB1 WHERE
   COL4 NE 'GLL SCLK 02724646:67:7:2'
 
   SELECT COL1 FROM TAB1 WHERE COL1 != NULL
 
   SELECT COL1 FROM TAB1 WHERE COL1 IS NULL
 
   SELECT COL1 FROM TAB1 WHERE COL1 IS NOT NULL
 
   SELECT COL1, COL2, COL3 FROM TAB1
   WHERE (COL1 BETWEEN 4 AND 6) AND (COL3 NOT LIKE "A%%")
   ORDER BY COL1, COL3
 
   SELECT COL4 FROM TAB1
   WHERE COL4 BETWEEN "1995 JAN 1 12:38" AND
   "October 23, 1995"
 
   SELECT COL1, COL2 FROM TAB1 WHERE
   NOT (    ( ( COL1 &lt;  COL2 ) AND ( COL1 &gt; 5   ) )  OR
            ( ( COL1 &gt;= COL2 ) AND ( COL2 &lt;= 10 ) )      )
 
 
   SELECT T1.COL1, T1.COL2, T2.COL2, T2.COL3
   FROM TABLE1 T1, TABLE2 T2
   WHERE T1.COL1 = T2.COL1
   AND T1.COL2 &gt; 5
   ORDER BY T1.COL1, T2.COL2
</PRE>
<BR><BR>
<A NAME="Examples of syntactically invalid queries"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Examples of syntactically invalid queries
</H3><P><BR><BR>
<PRE>
   SELECT TIME WHERE TIME
   LT 1991 JAN 1                      {FROM clause is absent}
 
   select time from table1 where
   time lt 1991 jan 1                 {time string is not
                                       quoted}
 
   select time from table1
   where time .lt. '1991 jan 1'       {operator should be lt}
 
   select cmd from table1
   where "cmd,6tmchg" != cmd          {value is on left side
                                       of operator}
 
   select event_type from table1
   where event_type eq ""             {quoted string is empty
                                       ---use " " to indicate
                                       a blank string}
 
   select event_type from table1
   where event_type = "COMMENT"
   order TIME                         {ORDER BY phrase is
                                       lacking BY keyword}
 
   select COL1 from table
   where COL1 eq MOC_EVENT            {literal string on
                                       right-hand-side of
                                       operator is not quoted}
</PRE>
<BR><BR>
<A NAME="Examples of semantically invalid queries"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Examples of semantically invalid queries
</H3><P><BR><BR>
   In the following examples, we'll assume that an application program has
   loaded a sequence EK containing two segments containing columns having
   the following names and attributes:
<P>
 
<PRE>
   TABLE1:
   ==========
 
     Column name        Data type         Size       Indexed?
     -----------        ---------         ----       --------
     EVENT_TYPE         CHARACTER*32      1          YES
     EVENT_PARAMETERS   CHARACTER*(*)     1          NO
     COMMENT            CHARACTER*80      VARIABLE   NO
 
 
   TABLE2:
   ==========
 
     Column name        Data type         Size       Indexed?
     -----------        ---------         ----       --------
     EVENT_TYPE         CHARACTER*32      1          YES
     EVENT_PARAMETERS   CHARACTER*80      1          NO
     COMMENT            CHARACTER*80      VARIABLE   NO
     COMMAND            CHARACTER*80      1          YES
</PRE>
   Then the following queries are semantically invalid:
<P>
 
<PRE>
   SELECT EVENT_PARAMETERS
   FROM TABLE1
   WHERE EVENT_DURATION = 7.0         {No column called
                                       EVENT_DURATION
                                       is present in a loaded
                                       EK}
 
   SELECT COMMENT FROM TABLE2
   WHERE COMMENT EQ "N/A"             {The COMMENT column does
                                       not have size 1 and
                                       therefore cannot be
                                       referenced in a query}
 
</PRE>
<BR><BR>
<A NAME="Sequence EK Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Sequence EK Files
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Sequence EKs are binary files conforming to the SPICE DAS architecture,
   which is described in the DAS Required Reading document, <a href="../req/das.html">das.req</a>. The
   SPICE file identification word occupying the first eight bytes of a
   properly created binary sequence EK file is ``DAS/EK ''. For more
   information on SPICE identification words refer to the Kernel Required
   Reading document, <a href="../req/kernel.html">kernel.req</a>. Most users will not need to understand the
   details of the structure of these files.
<P>
 
<BR><BR>
<A NAME="Segments"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Segments
</H3><P><BR><BR>
   Sequence EK files contain data organized in a series of logical tables
   called ``segments.'' This organization is logical, not physical---the
   physical layout of the data in the file is transparent to applications
   that access sequence EKs using the EK API.
<P>
 
   Each segment contains data belonging to one EK table. A sequence EK file
   may contain multiple segments for one or more distinct tables. Segments
   for a table may be distributed across multiple EK files.
<P>
 
   Spreading data for a table across multiple segments has no affect on
   query interpretation. However, performance degradation may result if a
   sequence EK file contains a very large number of segments.
<P>
 
<BR><BR>
<A NAME="The comment area"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The comment area
</H3><P><BR><BR>
   Because sequence EK files are based on the DAS architecture, they
   inherit the DAS ``comment area'' feature; this allows sequence EKs to
   store free-form text comments. Comments may be labels or other
   descriptive text that fully identifies the file and indicates its
   intended purpose.
<P>
 
   The contents of the comment area must be printable text. The comment
   area is line-oriented; text inserted into the comment area can be
   retrieved with the original line breaks preserved. It is recommended
   that text to be inserted into the comment area have no lines exceeding
   80 characters in length.
<P>
 
   See the section ``Sequence EK tools'' for information on the SPICE
   Toolkit utilities that access the comment area.
<P>
 
<BR><BR>
<A NAME="Sequence EK tools"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Sequence EK tools
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The SPICE Toolkit includes programs that may be used to create,
   summarize, or browse EK files. These are summarized below.
<P>
 
<BR><BR>
<A NAME="INSPEKT"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> INSPEKT
</H3><P><BR><BR>
   INSPEKT is an interactive program for browsing binary sequence EK files.
   INSPEKT presents a user interface similar to that of an interactive
   database program: a user can ``inspect'' one or more binary EK files by
   issuing queries in a SQL-like language; in response to each query,
   INSPEKT displays event data that satisfy the query. INSPEKT provides
   users with many options for formatting the output produced in response
   to queries.
<P>
 
   INSPEKT has an extensive, hyper-text style on-line help facility, and
   also has a detailed user's guide available as a paper document [284].
<P>
 
<BR><BR>
<A NAME="COMMNT"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> COMMNT
</H3><P><BR><BR>
   COMMNT is an interactive, menu-driven program that allows users to
   manipulate the comment area of binary EK, SPK, CK, and PCK files. The
   supported operations are:
<P>
 
<UL>
<TT>--</TT> Add or append comments to the comment area.
<BR><BR></UL>
<UL>
<TT>--</TT> Delete comments from the comment area.
<BR><BR></UL>
<UL>
<TT>--</TT> Extract comments from the comment area to a text file.
<BR><BR></UL>
<UL>
<TT>--</TT> Read the comment area.
<BR><BR></UL>
   COMMNT's user's guide, <a href="../ug/commnt.html">commnt.ug</a>, is NAIF Document [278].
<P>
 
<BR><BR>
<A NAME="TOXFR and TOBIN"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> TOXFR and TOBIN
</H3><P><BR><BR>
   Since sequence EKs are instances of DAS files, the DAS file transfer
   mechanisms apply. The CSPICE utilities TOXFR and TOBIN may be used to
   convert binary sequence EKs to ASCII transfer format and back to binary
   format. See the CONVERT user's guide, <a href="../ug/convert.html">convert.ug</a>, [333] for details.
<P>
 
<BR><BR>
<A NAME="SPACIT"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> SPACIT
</H3><P><BR><BR>
   The CSPICE utility SPACIT may also be used for converting sequence EKs
   between binary and transfer formats. SPACIT provides a rudimentary EK
   segment summary capability; however, INSPEKT is typically required to
   interactively extract useful information from a sequence EK.
<P>
 
<BR><BR>
<A NAME="Reading sequence EKs"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Reading sequence EKs
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<BR><BR>
<A NAME="Loading and unloading sequence EKs"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Loading and unloading sequence EKs
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In order for a program to query one or more sequence EK files, the files
   must first be made available to the EK subsystem. This process is called
   ``loading'' the files. Loading EK files is normally accomplished by
   calling the generic CSPICE kernel loader <a href="../cspice/furnsh_c.html">furnsh_c</a>:
<P>
 
<PRE>
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( &lt;fname&gt; );                 {Load SPICE kernel}
</PRE>
   A limited number of EK files may be loaded at any one time. The current
   maximum limit is 20 files.
<P>
 
   The inverse routine corresponding to <a href="../cspice/furnsh_c.html">furnsh_c</a> is <a href="../cspice/unload_c.html">unload_c</a>. unload_c
   removes a loaded kernel from the CSPICE system: the file is closed, and
   data structures referring to the file are updated to reflect the absence
   of the file.
<P>
 
   See [218] for further information on <a href="../cspice/furnsh_c.html">furnsh_c</a> and <a href="../cspice/unload_c.html">unload_c</a>.
<P>
 
   Before queries may be processed, any supplementary kernels required for
   time conversion should be loaded. To enable use of UTC times in queries,
   a leapseconds kernel is required. To enable use of SCLK values in
   queries, an SCLK kernel for the appropriate spacecraft clock must be
   loaded.
<P>
 
   All of the EK files loaded at any one time must have consistent table
   attributes: any two tables having the same name must have the same
   attributes, even if the tables belong to different files.
<P>
 
   Unlike the SPK subsystem, the EK subsystem supports no prioritization
   scheme for loaded kernels: no kernel supersedes another. Rather, all
   rows of all loaded EKs are considered during query processing.
<P>
 
<BR><BR>
<A NAME="Query-and-fetch interface"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Query-and-fetch interface
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The sequence EK subsystem's ``query and fetch'' capability is the
   principal high-level access mechanism for reading EK data. There are two
   steps to retrieving data using this mechanism:
<P>
 
<UL>
<TT>1.</TT> Specify the data of interest by issuing a query.
<BR><BR></UL>
<UL>
<TT>2.</TT> Fetch the data that satisfy the query.
<BR><BR></UL>
   Data comprising the query results may be fetched in random order.
<P>
 
<BR><BR>
<A NAME="Issuing queries"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Issuing queries
</H3><P><BR><BR>
   To issue a query to the sequence EK subsystem, use <a href="../cspice/ekfind_c.html">ekfind_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekfind_c.html">ekfind_c</a> ( &lt;query&gt;, &lt;lenout&gt;, &amp;nmrows, &amp;error, errmsg );
                                                           {Find rows
                                                            that
                                                            satisfy
                                                            query}
</PRE>
   With the arguments:
<P>
 
<DL><DT>
<B>
 `query'
</B><BR><BR>
<DD>
 is a string containing an EK query. See the section ``The EK query
language'' above for a complete description of the language.<BR>
</DL>
<DL><DT>
<B>
 `nmrows'
</B><BR><BR>
<DD>
 is the number of ``matching rows'': rows satisfying the query
constraints, if any. `nmrows' has a valid value only if the query
successfully executed.<BR>
</DL>
<DL><DT>
<B>
 `error'
</B><BR><BR>
<DD>
 is a logical flag indicating whether the query executed successfully.
If the input query is incorrect, `error' will return true.<BR>
</DL>
<DL><DT>
<B>
 `errmsg'
</B><BR><BR>
<DD>
 is a string containing an error diagnosis. `errmsg' has a valid value
only if when `error' is true.<BR>
</DL>
   Query errors fall into a few categories:
<P>
 
<UL>
<TT>--</TT> Scanning errors---these result from badly formed query in which <a href="../cspice/ekfind_c.html">ekfind_c</a>
could not identify all of the tokens. When these errors occur, EKFIND may
be too confused to give a helpful diagnostic message.
<BR><BR></UL>
<UL>
<TT>--</TT> Parsing errors---these result from a badly formed query that <a href="../cspice/ekfind_c.html">ekfind_c</a> was
able to separate into tokens but that <a href="../cspice/ekfind_c.html">ekfind_c</a> determined to be
syntactically invalid.
<BR><BR></UL>
<UL>
<TT>--</TT> Name resolution errors---these result from referencing invalid or ambiguous
column or table names in a query.
<BR><BR></UL>
<UL>
<TT>--</TT> Time resolution errors---these result when a failure occurs during the
parse of a time string.
<BR><BR></UL>
<UL>
<TT>--</TT> Miscellaneous semantic errors---these result from a syntactically valid
query that violates a limit or a restriction on values used in a query.
<BR><BR></UL>
   Some problems that may be encountered by <a href="../cspice/ekfind_c.html">ekfind_c</a> are not due to invalid
   queries, but are genuine error conditions:
<P>
 
<UL>
<TT>--</TT> No E-kernels are loaded at the time <a href="../cspice/ekfind_c.html">ekfind_c</a> is called.
<BR><BR></UL>
<UL>
<TT>--</TT> A time value is used in a query before a leapseconds kernel is loaded.
<BR><BR></UL>
<UL>
<TT>--</TT> A SCLK value is used in a query before an SCLK kernel for the appropriate
spacecraft clock has been loaded.
<BR><BR></UL>
   These problems cause a SPICE error to signal. The outputs of <a href="../cspice/ekfind_c.html">ekfind_c</a>
   are undefined in this case.
<P>
 
<BR><BR>
<A NAME="Fetching data from matching rows"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Fetching data from matching rows
</H3><P><BR><BR>
   The EK fetch functions <a href="../cspice/ekgc_c.html">ekgc_c</a>, <a href="../cspice/ekgd_c.html">ekgd_c</a>, and <a href="../cspice/ekgi_c.html">ekgi_c</a> return data of the
   indicated data type from rows satisfying an EK query.
<P>
 
   The EK fetch functions return one column entry element at a time, so it
   is not necessary to know in advance the size of the column entry.
<P>
 
   To fetch data from a character column, use
<P>
 
<PRE>
   <a href="../cspice/ekgc_c.html">ekgc_c</a> ( &lt;selidx&gt;, &lt;row&gt;, &lt;elment&gt;, &lt;lenout&gt;,        {Get character
             cdata, &amp;null, &amp;found );                     data}
</PRE>
   With the arguments:
<P>
 
<DL><DT>
<B>
 `selidx'
</B><BR><BR>
<DD>
 is the index of the column of interest in the SELECT clause of the
query. Column indices range from 0 : ncols-1 where `ncols' is the
number of columns referenced in the SELECT clause of the query.<BR>
</DL>
<DL><DT>
<B>
 `row'
</B><BR><BR>
<DD>
 is the index of the row from which to fetch. Row indices range from 0 :
nmrows-1 where `nmrows' is the number of matching rows returned by
<a href="../cspice/ekfind_c.html">ekfind_c</a>.<BR>
</DL>
<DL><DT>
<B>
 `elment'
</B><BR><BR>
<DD>
 is the index of the column entry element to fetch. Element indices
range from 0 : nelts-1 where `nelts' is the number of elements in the
column entry. It is not an error to specify an out-of-range value of
`elment': this will simply cause `found' to indicate no element was
found.<BR>
</DL>
<DL><DT>
<B>
 `lenout'
</B><BR><BR>
<DD>
 is the string length of the column name array `cnames'.<BR>
</DL>
<DL><DT>
<B>
 `cdata'
</B><BR><BR>
<DD>
 is a string containing the specified column entry element.<BR>
</DL>
<DL><DT>
<B>
 `null'
</B><BR><BR>
<DD>
 is a flag indicating whether the entry is null.<BR>
</DL>
<DL><DT>
<B>
 `found'
</B><BR><BR>
<DD>
 is a flag indicating whether the specified column entry element was
found.<BR>
</DL>
   To fetch double precision or TIME column entry elements, use <a href="../cspice/ekgd_c.html">ekgd_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekgd_c.html">ekgd_c</a> ( &lt;selidx&gt;, &lt;row&gt;, &lt;elment&gt;,
            &amp;ddata,   &amp;null, &amp;found   );               {Get d.p. data}
 
</PRE>
   The arguments have the same meanings as the corresponding arguments of
   <a href="../cspice/ekgc_c.html">ekgc_c</a>, except that `ddata' represents a double precision number.
<P>
 
   To fetch integer column entry elements, use <a href="../cspice/ekgi_c.html">ekgi_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekgi_c.html">ekgi_c</a> ( &lt;selidx&gt;, &lt;row&gt;, &lt;elment&gt;,
            &amp;idata,   &amp;null, &amp;found   );           {Get integer data}
</PRE>
   The arguments have the same meanings as the corresponding arguments of
   <a href="../cspice/ekgc_c.html">ekgc_c</a>, except that `idata' represents an integer.
<P>
 
<BR><BR>
<A NAME="Query support utilities"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Query support utilities
</H3><P><BR><BR>
   While an application can fetch array-valued column entries by calling
   the fetch routine of the appropriate data type in a loop, continuing
   until `found' is false, it is more elegant to find the size of the entry
   in advance. The function <a href="../cspice/eknelt_c.html">eknelt_c</a> provides this service:
<P>
 
<PRE>
   nelts = <a href="../cspice/eknelt_c.html">eknelt_c</a> ( &lt;selidx&gt;, &lt;row&gt; );      {Get number of elements}
</PRE>
   With the arguments:
<P>
 
<DL><DT>
<B>
 `selidx'
</B><BR><BR>
<DD>
 is the index of the column of interest in the SELECT clause of the
query. Column indices range from 0 : ncols-1 where `ncols' is the
number of columns referenced in the SELECT clause of the query.<BR>
</DL>
<DL><DT>
<B>
 `row'
</B><BR><BR>
<DD>
 is the index of the row from which to fetch. Row indices range from 0 :
nmrows-1 where `nmrows' is the number of matching rows returned by
<a href="../cspice/ekfind_c.html">ekfind_c</a>.<BR>
</DL>
<DL><DT>
<B>
 `nelts'
</B><BR><BR>
<DD>
 is the number of elements in the column entry.<BR>
</DL>
   The EK fetch functions <a href="../cspice/ekgc_c.html">ekgc_c</a>, <a href="../cspice/ekgd_c.html">ekgd_c</a>, <a href="../cspice/ekgi_c.html">ekgi_c</a>, together with the utility
   <a href="../cspice/eknelt_c.html">eknelt_c</a>, suffice for applications in which the SELECT clause of the
   query is known in advance. For such applications, the data types of the
   SELECT columns are known in advance, so it is clear which fetch function
   to call to retrieve any column entry.
<P>
 
   Some more complex EK applications may require the ability to fetch
   results from an arbitrary query. In order to do this, an application
   must be able to determine at run time the names and data types of the
   SELECT columns. If an application needs to unambiguously identify the
   columns, the names of the tables to which the columns belong are needed
   as well.
<P>
 
   Applications need not analyze a query to determine the fully qualified
   names and attributes of the SELECT columns---the EK subsystem provides
   the function <a href="../cspice/ekpsel_c.html">ekpsel_c</a> to do this job.
<P>
 
   Note: in the discussion below, there are references to substrings in the
   SELECT clause as ``expressions.'' Currently, the only supported
   expressions in the SELECT clause are column names. However, <a href="../cspice/ekpsel_c.html">ekpsel_c</a> has
   been designed to support possible query language enhancements, such as
   specification of general expressions in the SELECT clause.
<P>
 
   Calls to <a href="../cspice/ekpsel_c.html">ekpsel_c</a> are made as shown:
<P>
 
<PRE>
   <a href="../cspice/ekpsel_c.html">ekpsel_c</a>  ( &lt;query&gt;, &lt;msglen&gt;, &lt;tablen&gt;, &lt;collen&gt;,
               n,       xbegs,   xends,   xtypes,
               xclass,  tabs,    cols,    error,  errmsg ); { Parse
                                                              SELECT
                                                              clause }
</PRE>
   With the arguments:
<P>
 
<DL><DT>
<B>
 `query'
</B><BR><BR>
<DD>
 is the query to be analyzed.<BR>
</DL>
<DL><DT>
<B>
 `msglen'
</B><BR><BR>
<DD>
 is the length of the output error message.<BR>
</DL>
<DL><DT>
<B>
 `tablen'
</B><BR><BR>
<DD>
 is the length of the strings in the output table name array.<BR>
</DL>
<DL><DT>
<B>
 `collen'
</B><BR><BR>
<DD>
 is the length of the strings in the output column name array.<BR>
</DL>
<DL><DT>
<B>
 `n'
</B><BR><BR>
<DD>
 is the number of expressions (columns) in the SELECT clause of the
query.<BR>
</DL>
<DL><DT>
<B>
 `xbegs'
</B><BR><BR>
<DD>
 is an array of starting indices of expressions in the SELECT clause.<BR>
</DL>
<DL><DT>
<B>
 `xends'
</B><BR><BR>
<DD>
 is an array of ending indices of expressions in the SELECT clause. The
ith expression occupies query elements `query'[ `xbegs'[i] ] through
`query'[ `xends' [i] ].<BR>
</DL>
<DL><DT>
<B>
 `xtypes'
</B><BR><BR>
<DD>
 is an array of data types of the expressions in the SELECT clause of
the query.<BR>
</DL>
<DL><DT>
<B>
 `xclass'
</B><BR><BR>
<DD>
 is an array of classes of the expressions in the SELECT clause of the
query. The ith element of `xclass' indicates whether the ith SELECT
expression is a column name, a function, or a more general expression.
The elements of `xclass' have data type SpiceEKExprClass. See the
header SpiceEK.h for details.<BR>
</DL>
<DL><DT>
<B>
 `tabs'
</B><BR><BR>
<DD>
 is an array containing table names corresponding to the SELECT columns.
Actual table names are returned, even if the column names are qualified
by aliases in the query. Elements of `tabs' corresponding to SELECT
expressions that are not column names are undefined.<BR>
</DL>
<DL><DT>
<B>
 `cols'
</B><BR><BR>
<DD>
 is an array containing unqualified versions of the column names
appearing in the SELECT clause. The ith element of `cols' is defined
only if the ith expression in the SELECT clause is a column name.<BR>
</DL>
<DL><DT>
<B>
 `error'
</B><BR><BR>
<DD>
 is a flag indicating whether a parsing error occurred while analyzing
the query. If an error occurred, the other outputs, with the exception
of the error message, are undefined.<BR>
</DL>
<DL><DT>
<B>
 `errmsg'
</B><BR><BR>
<DD>
 is a string containing an error diagnosis, if a parsing error occurred.
Otherwise, ERRMSG is returned empty.<BR>
</DL>
<BR><BR>
<A NAME="Record-oriented reader interface"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Record-oriented reader interface
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The EK record-oriented reader functions provide applications with a
   low-level interface for examining EK data. Using these functions, an
   application has direct access to specified EK column entries.
<P>
 
<BR><BR>
<A NAME="Opening files for record-oriented reading"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Opening files for record-oriented reading
</H3><P><BR><BR>
   The record-oriented readers may be used to read EKs open for either read
   or write access. If the EK is to be opened for read access, the function
   <a href="../cspice/ekopr_c.html">ekopr_c</a> is convenient:
<P>
 
<PRE>
   <a href="../cspice/ekopr_c.html">ekopr_c</a> ( &lt;fname&gt;, &amp;handle );            {EK, open for read}
</PRE>
   If the EK to be read is to be queried, then the EK should be loaded
   using <a href="../cspice/furnsh_c.html">furnsh_c</a>.
<P>
 
<PRE>
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( &lt;fname&gt; );                 {Load SPICE kernel}
</PRE>
   The file's handle may be obtained using a call to the CSPICE function
   <a href="../cspice/kinfo_c.html">kinfo_c</a>.
<P>
 
<BR><BR>
<A NAME="Column entry readers"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Column entry readers
</H3><P><BR><BR>
   The record-oriented readers return a specified column entry from a
   specified EK. To read a character column entry, call <a href="../cspice/ekrcec_c.html">ekrcec_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekrcec_c.html">ekrcec_c</a>  ( &lt;handle&gt;, &lt;segno&gt;, &lt;recno&gt;, &lt;column&gt;,   {read character
               &lt;lenout&gt;  &amp;nvals,  cvals,   isnull   );  column entry}
</PRE>
   With the arguments:
<P>
 
<DL><DT>
<B>
 `handle'
</B><BR><BR>
<DD>
 is the file handle of the sequence EK to be read.<BR>
</DL>
<DL><DT>
<B>
 `segno'
</B><BR><BR>
<DD>
 is the ordinal position in the EK of the segment containing the desired
column entry.<BR>
</DL>
<DL><DT>
<B>
 `segno'
</B><BR><BR>
<DD>
 is the ordinal position in the segment of the record containing the
desired column entry.<BR>
</DL>
<DL><DT>
<B>
 `column'
</B><BR><BR>
<DD>
 is the name of the column containing the desired entry.<BR>
</DL>
<DL><DT>
<B>
 `lenout'
</B><BR><BR>
<DD>
 is the string length of the elements of the array `cvals'.<BR>
</DL>
<DL><DT>
<B>
 `nvals'
</B><BR><BR>
<DD>
 is the number of array elements in the column entry.<BR>
</DL>
<DL><DT>
<B>
 `cvals'
</B><BR><BR>
<DD>
 is the column entry itself. Note that CVALS must have sufficient size
to accommodate the entire column entry. CVALS is defined only if the
column entry is non-null.<BR>
</DL>
<DL><DT>
<B>
 `isnull'
</B><BR><BR>
<DD>
 is a flag indicating whether the column entry is null.<BR>
</DL>
   To read a double precision or TIME column entry, call <a href="../cspice/ekrced_c.html">ekrced_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekrced_c.html">ekrced_c</a>  ( &lt;handle&gt;, &lt;segno&gt;,  &lt;recno&gt;, &lt;column&gt;,    {read d.p.
               &amp;nvals,   dvals,    isnull            );   column entry}
</PRE>
   The arguments have the same meanings as the corresponding arguments of
   <a href="../cspice/ekrced_c.html">ekrced_c</a>, except that `dvals' represents a double precision array.
<P>
 
   To read an integer column entry, call <a href="../cspice/ekrcei_c.html">ekrcei_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekrcei_c.html">ekrcei_c</a>  ( &lt;handle&gt;, &lt;segno&gt;,  &lt;recno&gt;, &lt;column&gt;,     {read integer
               &amp;nvals,   ivals,    isnull            );    column entry}
</PRE>
   The arguments have the same meanings as the corresponding arguments of
   <a href="../cspice/ekrcec_c.html">ekrcec_c</a>, except that `ivals' represents an integer array.
<P>
 
<BR><BR>
<A NAME="Informational functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Informational functions
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
<BR><BR>
<A NAME="Summarizing EK files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Summarizing EK files
</H3><P><BR><BR>
   To summarize an EK file, the file must be open for read or write access,
   and the file handle must be available. If the file is open for write
   access, the file must be structurally valid: for example, a fast write
   operation on the file must not be partially executed.
<P>
 
   The number of segments in an EK is found by calling <a href="../cspice/eknseg_c.html">eknseg_c</a>:
<P>
 
<PRE>
   n = <a href="../cspice/eknseg_c.html">eknseg_c</a> ( &lt;handle&gt; );              {Return number of segments}
</PRE>
   The summary of the segment at ordinal position `segno' is returned by
   <a href="../cspice/ekssum_c.html">ekssum_c</a>:
<P>
 
<PRE>
   n = <a href="../cspice/ekssum_c.html">ekssum_c</a> ( &lt;handle&gt;, &lt;segno&gt;, &amp;segsum );       {Summarize
                                                       segment}
</PRE>
   With the arguments:
<P>
 
<DL><DT>
<B>
 `handle'
</B><BR><BR>
<DD>
 is the file handle of the sequence EK containing the segment of
interest.<BR>
</DL>
<DL><DT>
<B>
 `segno'
</B><BR><BR>
<DD>
 is the ordinal position in the EK of the segment to be summarized.<BR>
</DL>
<DL><DT>
<B>
 `segsum'
</B><BR><BR>
<DD>
 is an structure of type SpiceEKSegSum which describes the schema of the
segment. See the header SpiceEK.h for details.<BR>
</DL>
<BR><BR>
<A NAME="Summarizing loaded tables"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Summarizing loaded tables
</H3><P><BR><BR>
   A ``loaded EK table'' is a virtual table consisting of the union of all
   rows of data from segments having a given table name and schema, where
   the segments belong to loaded EKs. These tables exist in the EK query
   subsystem when EKs are loaded using <a href="../cspice/furnsh_c.html">furnsh_c</a>.
<P>
 
   The number of loaded tables may be found by calling <a href="../cspice/ekntab_c.html">ekntab_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekntab_c.html">ekntab_c</a> ( &amp;n );              {Return number of loaded tables}
</PRE>
   The name of the nth loaded table may be found by calling <a href="../cspice/ektnam_c.html">ektnam_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ektnam_c.html">ektnam_c</a> ( &lt;n&gt;, &lt;lenout&gt;, table );         {Return table name}
</PRE>
   The number of columns in a specified, loaded table may be found by
   calling <a href="../cspice/ekccnt_c.html">ekccnt_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekccnt_c.html">ekccnt_c</a> ( &lt;table&gt;, &amp;ccount );             {Return column count}
</PRE>
   The name and attributes of the column having a specified ordinal
   position within a specified, loaded table may be found by calling
   <a href="../cspice/ekcii_c.html">ekcii_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekcii_c.html">ekcii_c</a> ( &lt;table&gt;, &lt;cindex&gt;, &lt;lenout&gt;,
             column,  &amp;attdsc            );     {Return attributes
                                                 of column specified
                                                 by index}
</PRE>
   With the arguments:
<P>
 
<DL><DT>
<B>
 `table'
</B><BR><BR>
<DD>
 is the name of the table containing the column of interest.<BR>
</DL>
<DL><DT>
<B>
 `cindex'
</B><BR><BR>
<DD>
 is the ordinal position of the column of interest within its table.<BR>
</DL>
<DL><DT>
<B>
 `column'
</B><BR><BR>
<DD>
 is the returned column name.<BR>
</DL>
<DL><DT>
<B>
 `attdsc'
</B><BR><BR>
<DD>
 is the returned column attribute descriptor. See the header file
SpiceEK.h for details.<BR>
</DL>
<BR><BR>
<A NAME="Writing sequence EKs"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Writing sequence EKs
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<BR><BR>
<A NAME="Introduction0"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Introduction
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   This chapter describes how to create new sequence EKs and update
   existing ones.
<P>
 
   The basic sequence of operations by which a new sequence EK is created
   is:
<P>
 
<UL>
<TT>1.</TT> Open a new sequence EK. This step prepares the sequence EK for the addition
of data.
<BR><BR></UL>
<UL>
<TT>2.</TT> Add one or more segments to the sequence EK. A segment may be created using
the record-oriented writers or the fast writers.
<BR><BR></UL>
<UL>
<TT>3.</TT> Close the sequence EK. This step writes bookkeeping information to the
file, flushes to the file any remaining buffered data that have not been
physically written out, and closes the file.
<BR><BR></UL>
   Existing segments in a sequence EK may be updated: new records may be
   added, records may be deleted, and individual column entries in existing
   segments may be updated.
<P>
 
   An existing, closed sequence EK may be opened for write access, at which
   point all operations valid for a new sequence EK may be performed on the
   file.
<P>
 
   The comment area of a sequence EK may be written to when the file is
   open for write access.
<P>
 
<BR><BR>
<A NAME="Opening a sequence EK for writing"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Opening a sequence EK for writing
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
<BR><BR>
<A NAME="Beginning a new sequence EK"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Beginning a new sequence EK
</H3><P><BR><BR>
   A new sequence EK is opened and prepared for writing using a call to
   <a href="../cspice/ekopn_c.html">ekopn_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekopn_c.html">ekopn_c</a> (  &lt;fname&gt;, &lt;ifname&gt;, &lt;ncomch&gt;, &amp;handle );  {Open new EK}
</PRE>
   With the arguments:
<P>
 
<DL><DT>
<B>
 `fname'
</B><BR><BR>
<DD>
 is the name of the new sequence EK.<BR>
</DL>
<DL><DT>
<B>
 `ifname'
</B><BR><BR>
<DD>
 is the internal file name of the new sequence EK. This name may be up
to 60 characters in length; it must contain only printing characters
and blanks. `ifname' may be left blank.<BR>
</DL>
<DL><DT>
<B>
 `ncomch'
</B><BR><BR>
<DD>
 is the number of comment characters to reserve in the comment area.
Zero is an acceptable value for `ncomch'. However, reserving sufficient
space for comments speeds up addition of comments after the file is
written, since data records will not need to be shifted to make room.
See the COMMNT User's Guide, <a href="../ug/commnt.html">commnt.ug</a>, for further information.<BR>
</DL>
<DL><DT>
<B>
 `handle'
</B><BR><BR>
<DD>
 is the returned file handle. `handle' will be used to identify the file
to other sequence EK functions.<BR>
</DL>
<BR><BR>
<A NAME="Opening an existing sequence EK for writing"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Opening an existing sequence EK for writing
</H3><P><BR><BR>
   Use <a href="../cspice/ekopw_c.html">ekopw_c</a> to open an existing sequence EK for writing:
<P>
 
<PRE>
   <a href="../cspice/ekopw_c.html">ekopw_c</a> ( &lt;fname&gt;, &amp;handle );            {Open EK for writing}
</PRE>
   The arguments of <a href="../cspice/ekopw_c.html">ekopw_c</a> have the same meanings as the corresponding
   arguments of <a href="../cspice/ekopn_c.html">ekopn_c</a>.
<P>
 
<BR><BR>
<A NAME="Choosing a writing method"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Choosing a writing method
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Before a new segment is started, the writing method must be selected:
   the choices are ``record-oriented'' or ``fast.''
<P>
 
   Record-oriented writing allows records to be added to a segment one at a
   time; this approach simplifies creating records from a streaming data
   source. Records may be added to a segment in arbitrary order. Also, it
   is possible to build multiple segments simultaneously using the
   record-oriented writers.
<P>
 
   The significant limitation of the record-oriented approach is that it is
   slow, particularly if the segment being written contains indexed
   columns. When execution speed is critical, it may be advisable to use
   the ``fast writers.'' These routines can create a segment as much as 100
   times faster than their record-oriented counterparts. However, the fast
   writers require all of the segment's data to be staged before the
   segment is written.
<P>
 
   Below, we discuss aspects of segment creation common to both writing
   approaches. See the sections ``Using the record-oriented sequence EK
   writers'' and ``Using the fast writers'' below for specifics on how to
   implement either approach.
<P>
 
<BR><BR>
<A NAME="Specifying segment attributes"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Specifying segment attributes
</H3><P><BR><BR>
   When starting a new segment using either the record-oriented or fast
   writers, it is necessary to specify the name of the table the segment
   belongs to and the names and attributes of the columns in the table.
   When using the fast writers, it is also necessary to specify the number
   of rows in the segment.
<P>
 
<BR><BR>
<A NAME="Table and column names"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Table and column names
</H3><P><BR><BR>
   Table and column names must start with a letter and contain only
   characters from the set
<P>
 
<PRE>
   {A-Z, a-z, 0-9, $,  _}
</PRE>
   Case is not significant.
<P>
 
   Table names must not exceed SPICE_EK_TNAMSZ (see header file SpiceEK.h)
   characters in length. Column names must not exceed SPICE_EK_CNAMSZ (see
   header file SpiceEK.h) characters in length.
<P>
 
<BR><BR>
<A NAME="Column declarations"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Column declarations
</H3><P><BR><BR>
   Column attributes are specified in arrays of strings called ``column
   declarations.'' There is one declaration per column. The syntax for
   column declarations is independent of the writing method.
<P>
 
   Column declarations are strings that contain ``keyword=value''
   assignments that define the attributes of the columns to which they
   apply. The column attributes defined by a column declaration are:
<P>
 
<PRE>
   DATATYPE
   SIZE
   &lt;is the column indexed?&gt;
   &lt;does the column allow null values?&gt;
</PRE>
   When a segment is started using <a href="../cspice/ekbseg_c.html">ekbseg_c</a> or <a href="../cspice/ekifld_c.html">ekifld_c</a>, an array of column
   declarations must be supplied as an input. The form of a column
   declaration string is a list of ``keyword=value'' assignments, delimited
   by commas, as shown:
<P>
 
<PRE>
   "DATATYPE  = &lt;type&gt;, "
   "SIZE      = &lt;size&gt;, "
   "INDEXED   = &lt;boolean&gt;, "
   "NULLS_OK  = &lt;boolean&gt;"
</PRE>
   For example, an indexed, scalar, integer column that does not allow null
   values would have the declaration
<P>
 
<PRE>
   "DATATYPE  = INTEGER, "
   "SIZE      = 1, "
   "INDEXED   = TRUE, "
   "NULLS_OK  = FALSE"
</PRE>
   Commas are required to separate the assignments within declarations;
   white space is optional; case is not significant.
<P>
 
   The order in which the attribute keywords are listed in the declaration
   is not significant.
<P>
 
   Data type specifications are required for each column.
<P>
 
   Each column entry is effectively an array, each element of which has the
   declared data type. The SIZE keyword indicates how many elements are in
   each entry of the column. Note that only scalar-valued columns (those
   for which SIZE = 1) may be referenced in query constraints. A size
   assignment has the syntax
<P>
 
<PRE>
   SIZE = &lt;integer&gt;
</PRE>
   or
<P>
 
<PRE>
   SIZE = VARIABLE
</PRE>
   The size value defaults to 1 if omitted.
<P>
 
   The DATATYPE keyword defines the data type of column entries. The
   DATATYPE assignment syntax has any of the forms
<P>
 
<PRE>
   DATATYPE = CHARACTER*(&lt;length&gt;)
   DATATYPE = CHARACTER*(*)
   DATATYPE = DOUBLE PRECISION
   DATATYPE = INTEGER
   DATATYPE = TIME
</PRE>
   As the datatype declaration syntax suggests, character strings may have
   fixed or variable length. For example, a fixed-length string of 80
   characters is indicated by the declaration
<P>
 
<PRE>
   DATATYPE = CHARACTER*(80)
</PRE>
   while a variable-length string is indicated by an asterisk:
<P>
 
<PRE>
   DATATYPE = CHARACTER*(*)
</PRE>
   Variable-length strings have a practical length limit of 1024
   characters: the sequence EK writers allow one to write a scalar string
   of any length, but the sequence EK query functions will truncate a
   string whose length exceeds this limit.
<P>
 
   Variable-length strings are allowed only in scalar character columns.
<P>
 
   Optionally, scalar-valued columns may be indexed. Indexing can greatly
   speed up the processing of some queries, because indexing allows data to
   be found by a binary, rather than linear, search.
<P>
 
   Each index increases the size of the sequence EK file by an amount
   greater than or equal to the space occupied by two integers times the
   number of rows in the affected table, so for potentially large sequence
   EK files, the issue of whether or not to index a column deserves some
   consideration.
<P>
 
   To create an index for a column, use the assignment
<P>
 
<PRE>
   INDEXED = TRUE
</PRE>
   By default, columns are not indexed.
<P>
 
   Optionally, any column can allow null values; this is indicated by the
   assignment
<P>
 
<PRE>
   NULLS_OK = TRUE
</PRE>
   in the column declaration. By default, null values are not allowed in
   column entries.
<P>
 
<BR><BR>
<A NAME="Consistency of schemas"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Consistency of schemas
</H3><P><BR><BR>
   All segments belonging to a given table, that is having the same table
   name, must have identical schemas: the same set of column names, with
   each pair of identically-named columns having identical declarations.
<P>
 
   The sequence EK writer functions don't diagnose segment schema
   inconsistencies (to do so would be cumbersome at best, since
   inconsistencies could occur in separate files). However, loading into
   the sequence EK query system segments with identical table names but
   inconsistent column declarations will result in an error diagnosis.
<P>
 
<BR><BR>
<A NAME="Using the record-oriented sequence EK writers"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Using the record-oriented sequence EK writers
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
<BR><BR>
<A NAME="Beginning a segment"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Beginning a segment
</H3><P><BR><BR>
   The first step in beginning a new segment using the record-oriented
   writers is to define the new segment's schema. This is done by calling
   <a href="../cspice/ekbseg_c.html">ekbseg_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekbseg_c.html">ekbseg_c</a> ( &lt;handle&gt;, &lt;tabnam&gt;, &lt;ncols&gt;, &lt;cnmlen&gt;,    {Begin
              &lt;cnames&gt;, &lt;declen&gt;, &lt;decls&gt;, &amp;segno   );   segment}
</PRE>
   The inputs to <a href="../cspice/ekbseg_c.html">ekbseg_c</a> are described below:
<P>
 
<DL><DT>
<B>
 `handle'
</B><BR><BR>
<DD>
 is the file handle returned by the function used to open the sequence
EK.<BR>
</DL>
<DL><DT>
<B>
 `tabnam'
</B><BR><BR>
<DD>
 is the name of the table to which the new segment belongs.<BR>
</DL>
<DL><DT>
<B>
 `ncols'
</B><BR><BR>
<DD>
 is the number of columns in the table.<BR>
</DL>
<DL><DT>
<B>
 `cnmlen'
</B><BR><BR>
<DD>
 is the string length of the column name array `cnames'.<BR>
</DL>
<DL><DT>
<B>
 `cnames'
</B><BR><BR>
<DD>
 is an array containing the names of the columns in the table.<BR>
</DL>
<DL><DT>
<B>
 `declen'
</B><BR><BR>
<DD>
 is the string length of the column declaration array `decls'.<BR>
</DL>
<DL><DT>
<B>
 `decls'
</B><BR><BR>
<DD>
 is an array containing the declarations for each column. See the
section ``Column declarations'' above for details.<BR>
</DL>
   The sole output from <a href="../cspice/ekbseg_c.html">ekbseg_c</a> is:
<P>
 
<DL><DT>
<B>
 `segno'
</B><BR><BR>
<DD>
 This is the number of the new segment: the ordinal position of the
segment in the file. Segment numbers start at 0 in CSPICE.<BR>
</DL>
<BR><BR>
<A NAME="Adding records to a segment"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Adding records to a segment
</H3><P><BR><BR>
   The record-oriented sequence EK write functions support building
   sequence EK segments one record at a time.
<P>
 
   A new segment is prepared for record-oriented writing using a call to
   <a href="../cspice/ekbseg_c.html">ekbseg_c</a> (see ``Starting a new segment'' above). Next, records are added
   to the segment. Records may be appended or may be inserted into the
   segment.
<P>
 
   To append a new, empty record to a segment, use <a href="../cspice/ekappr_c.html">ekappr_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekappr_c.html">ekappr_c</a> ( &lt;handle&gt;, &lt;segno&gt;, &amp;recno );         {Append record}
</PRE>
   With the arguments:
<P>
 
<DL><DT>
<B>
 `handle'
</B><BR><BR>
<DD>
 is the EK's file handle.<BR>
</DL>
<DL><DT>
<B>
 `segno'
</B><BR><BR>
<DD>
 is the number of the segment to write to. `segno' must be a segment
number obtained from <a href="../cspice/ekbseg_c.html">ekbseg_c</a>.<BR>
</DL>
<DL><DT>
<B>
 `recno'
</B><BR><BR>
<DD>
 is the number of the new record; RECNO is an output argument.<BR>
</DL>
   To insert a new, empty record into a segment, use <a href="../cspice/ekinsr_c.html">ekinsr_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekinsr_c.html">ekinsr_c</a> ( &lt;handle&gt;, &lt;segno&gt;, &lt;recno&gt; );         {Insert record}
</PRE>
   The arguments are the same as those of <a href="../cspice/ekappr_c.html">ekappr_c</a>, except that here
   `recno' is an input. `recno' is the desired ordinal position of the new
   record: `recno' must be in the range
<P>
 
<PRE>
   0 : nrec
</PRE>
   where `nrec' is the number of records already in the segment.
<P>
 
   Each new record starts out empty. The column entries in the record are
   filled in one-by-one using calls to the ``add column entry'' functions
   <a href="../cspice/ekacec_c.html">ekacec_c</a>, <a href="../cspice/ekaced_c.html">ekaced_c</a>, and <a href="../cspice/ekacei_c.html">ekacei_c</a>. The column entries of a record may be
   written in any order.
<P>
 
   Character column entries are written by <a href="../cspice/ekacec_c.html">ekacec_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekacec_c.html">ekacec_c</a> ( &lt;handle&gt;, &lt;segno&gt;,  &lt;recno&gt;, &lt;column&gt;,      {Add character
              &lt;nvals&gt;,  &lt;vallen&gt;, &lt;cvals&gt;, &lt;isnull&gt;  );    column entry}
</PRE>
   With the arguments:
<P>
 
<DL><DT>
<B>
 `handle'
</B><BR><BR>
<DD>
 is the DAS file handle obtained from <a href="../cspice/ekopn_c.html">ekopn_c</a>.<BR>
</DL>
<DL><DT>
<B>
 `segno'
</B><BR><BR>
<DD>
 is the number of the segment to write to. `segno' must be a segment
number obtained from <a href="../cspice/ekbseg_c.html">ekbseg_c</a>.<BR>
</DL>
<DL><DT>
<B>
 `recno'
</B><BR><BR>
<DD>
 is the number of the new record; `recno' is an output argument.<BR>
</DL>
<DL><DT>
<B>
 `column'
</B><BR><BR>
<DD>
 is the name of the column to which data is to be written.<BR>
</DL>
<DL><DT>
<B>
 `nvals'
</B><BR><BR>
<DD>
 is the number of elements in the column entry. For scalar entries,
`nvals' is 1. For null-valued entries, NVALS is ignored.<BR>
</DL>
<DL><DT>
<B>
 `vallen'
</B><BR><BR>
<DD>
 is the string length of the elements of `cvals'.<BR>
</DL>
<DL><DT>
<B>
 `cvals_len'
</B><BR><BR>
<DD>
 is the string length of the elements of `cvals'.<BR>
</DL>
<DL><DT>
<B>
 `cvals'
</B><BR><BR>
<DD>
 is the string or array of strings comprising the column entry. `cvals'
is ignored if the entry being added is null.<BR>
</DL>
<DL><DT>
<B>
 `isnull'
</B><BR><BR>
<DD>
 is a boolean flag indicating whether the entry being added is null. If
the column has fixed-length, variable-size entries, and the entry being
added is null, the size of the entry is considered to be 1.<BR>
</DL>
   Double precision column entries are written by <a href="../cspice/ekaced_c.html">ekaced_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekaced_c.html">ekaced_c</a> ( &lt;handle&gt;, &lt;segno&gt;,  &lt;recno&gt;, &lt;column&gt;,      {Add d.p.
              &lt;nvals&gt;,  &lt;dvals&gt;,  &lt;isnull&gt;          );     column entry}
</PRE>
   The arguments have the same meanings as the corresponding arguments of
   <a href="../cspice/ekacec_c.html">ekacec_c</a>, except that `dvals' represents a double precision array.
<P>
 
   Values of type TIME are also added using <a href="../cspice/ekaced_c.html">ekaced_c</a>. When a column
   contains TIME values (as indicated by its declared data type), the
   values are stored as ephemeris seconds past J2000 TDB. When starting
   with UTC or SCLK time values, the CSPICE conversion routines <a href="../cspice/str2et_c.html">str2et_c</a> or
   <a href="../cspice/scs2e_c.html">scs2e_c</a> may be used to obtain equivalent double precision TDB values.
   See the <a href="../req/time.html">TIME.REQ</a> or <a href="../req/sclk.html">SCLK.REQ</a> Required Reading for details.
<P>
 
   Integer column entries are written by <a href="../cspice/ekacei_c.html">ekacei_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekacei_c.html">ekacei_c</a> ( &lt;handle&gt;, &lt;segno&gt;,  &lt;recno&gt;, &lt;column&gt;,     {Add integer
              &lt;nvals&gt;,  &lt;ivals&gt;,  &lt;isnull&gt;          );    column entry}
</PRE>
   The arguments have the same meanings as the corresponding arguments of
   <a href="../cspice/ekacec_c.html">ekacec_c</a>, except that `ivals' represents an integer array.
<P>
 
   A record must have all of its column entries written in order to be
   valid: column entries do not have default values.
<P>
 
   No action is required to ``finish`` a segment created by the
   record-oriented writers, although <a href="../cspice/ekcls_c.html">ekcls_c</a> must be called to close the
   file when all segments have been written.
<P>
 
<BR><BR>
<A NAME="Using the fast writers"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Using the fast writers
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The sequence EK ``fast write'' capability (referred to as ``fast load''
   in older documentation) allows construction of a sequence EK segment
   much more quickly than is possible with the record-oriented writers, at
   the expense of some flexibility.
<P>
 
   The fast write approach involves creating one new segment at a time.
   Segments are constructed one column at a time: each column is added to a
   segment in one shot.
<P>
 
   In order to add a segment to a sequence EK, the sequence EK must be open
   for write access. New sequence EK files are opened by calling <a href="../cspice/ekopn_c.html">ekopn_c</a>;
   existing sequence EKs are opened for writing by calling <a href="../cspice/ekopw_c.html">ekopw_c</a>.
<P>
 
   The sequence of operations required to create a segment using the fast
   write functions is:
<P>
 
<UL>
<TT>1.</TT> Initiate a fast write operation by calling <a href="../cspice/ekifld_c.html">ekifld_c</a>. This call defines the
segment's schema and size. The number of rows in the segment must be known
at the time this call is made.
<BR><BR></UL>
<UL>
<TT>2.</TT> Add data columns to the segment by calling <a href="../cspice/ekaclc_c.html">ekaclc_c</a>, <a href="../cspice/ekacld_c.html">ekacld_c</a>, or <a href="../cspice/ekacli_c.html">ekacli_c</a>.
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Because each column is created by a single function call, all data
constituting the column, along with null flags and entry size information,
must be buffered in arrays declared or allocated by the user's application.
<BR><BR></UL>
<UL>
<TT>3.</TT> Complete the segment by calling <a href="../cspice/ekffld_c.html">ekffld_c</a>. This call writes out bookkeeping
information required to make the segment readable.
<BR><BR></UL>
   When all segments in a sequence EK are complete, the sequence EK must be
   closed by calling <a href="../cspice/ekcls_c.html">ekcls_c</a>.
<P>
 
<BR><BR>
<A NAME="Initiating a fast write"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Initiating a fast write
</H3><P><BR><BR>
   The first step in creating a new segment using the fast writers is to
   define the new segment's attributes, specifically its schema and the
   number of rows in the segment. This is done by calling <a href="../cspice/ekifld_c.html">ekifld_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekifld_c.html">ekifld_c</a> ( &lt;handle&gt;, &lt;tabnam&gt;, &lt;ncols&gt;,  &lt;nrows&gt;,     {Initiate
              &lt;cnmlen&gt;, &lt;cnames&gt;, &lt;declen&gt;, &lt;decls&gt;,      fast write }
              &amp;segno,    rcptrs                     );
</PRE>
   The inputs to <a href="../cspice/ekifld_c.html">ekifld_c</a> are described below.
<P>
 
<DL><DT>
<B>
 `handle'
</B><BR><BR>
<DD>
 is the file handle returned by the function used to open the sequence
EK.<BR>
</DL>
<DL><DT>
<B>
 `tabnam'
</B><BR><BR>
<DD>
 is the name of the table to which the new segment belongs.<BR>
</DL>
<DL><DT>
<B>
 `ncols'
</B><BR><BR>
<DD>
 is the number of columns in the table.<BR>
</DL>
<DL><DT>
<B>
 `nrows'
</B><BR><BR>
<DD>
 is the number of rows in the new segment.<BR>
</DL>
<DL><DT>
<B>
 `cnmlen'
</B><BR><BR>
<DD>
 is the string length of the column name array `cnames'.<BR>
</DL>
<DL><DT>
<B>
 `cnames'
</B><BR><BR>
<DD>
 is an array containing the names of the columns in the table.<BR>
</DL>
<DL><DT>
<B>
 `declen'
</B><BR><BR>
<DD>
 is the string length of the column declaration array `decls'.<BR>
</DL>
<DL><DT>
<B>
 `decls'
</B><BR><BR>
<DD>
 is an array containing the declarations for each column. The
declaration syntax is identical to that used by the record-oriented
function <a href="../cspice/ekbseg_c.html">ekbseg_c</a>. See the section ``Column declarations'' above for
details.<BR>
</DL>
   The outputs from <a href="../cspice/ekifld_c.html">ekifld_c</a> are:
<P>
 
<DL><DT>
<B>
 `segno'
</B><BR><BR>
<DD>
 This is the number of the new segment: the ordinal position of the
segment in the file. Segment numbers start at 0 in CSPICE.<BR>
</DL>
<DL><DT>
<B>
 `rcptrs'
</B><BR><BR>
<DD>
 This is an integer work space array the caller must not modify.
`rcptrs' must have dimension at least equal to the number of rows in
the segment. `rcptrs' is passed as an input to the other fast writer
routines.<BR>
</DL>
<BR><BR>
<A NAME="Adding columns to the segment"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Adding columns to the segment
</H3><P><BR><BR>
   There are three fast writer routines used to add columns to a segment;
   the routine to use depends on the data type of the column.
<P>
 
   To add a character column to a segment, call <a href="../cspice/ekaclc_c.html">ekaclc_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekaclc_c.html">ekaclc_c</a> ( &lt;handle&gt;, &lt;segno&gt;,  &lt;column&gt;, &lt;vallen&gt;,   {Add
              &lt;cvals&gt;,  &lt;entszs&gt;, &lt;nlflgs&gt;, &lt;rcptrs&gt;,    character
              wkindx                                 );  column}
 
 
</PRE>
   The inputs to <a href="../cspice/ekaclc_c.html">ekaclc_c</a> are described below.
<P>
 
<DL><DT>
<B>
 `handle'
</B><BR><BR>
<DD>
 is the file handle returned by the function used to open the sequence
EK.<BR>
</DL>
<DL><DT>
<B>
 `segno'
</B><BR><BR>
<DD>
 is the segment number obtained from <a href="../cspice/ekifld_c.html">ekifld_c</a>.<BR>
</DL>
<DL><DT>
<B>
 `column'
</B><BR><BR>
<DD>
 is the name of the column to be added.<BR>
</DL>
<DL><DT>
<B>
 `vallen'
</B><BR><BR>
<DD>
 is the string length of the character value array `cvals'.<BR>
</DL>
<DL><DT>
<B>
 `cvals'
</B><BR><BR>
<DD>
 is an array containing the entire set of column entries for the
specified column. The entries are listed in row-order: the column entry
for the first row of the segment is first, followed by the column entry
for the second row, and so on. If the column is array-valued, the
successive elements of each column entry occupy successive strings in
the `cvals' array.<BR>
</DL>
<DL><DT>
<B>
 
</B><BR><BR>
<DD>
 Regarding null values: for columns having fixed-size entries, a null
entry must be allocated the same amount of space occupied by a non-null
entry in the array `cvals'. For columns having variable-size entries,
null entries do not require any space in the `cvals' array, but in any
case must have their allocated space described correctly by the
corresponding element of the `entszs' array.<BR>
</DL>
<DL><DT>
<B>
 `entszs'
</B><BR><BR>
<DD>
 is an array of integers, each specifying the number of array elements
in the corresponding column entry. The values in the array `entszs' are
used only for columns having variable-size entries, but in all cases,
`entszs' must have dimension at least equal to the number of rows in
the segment. For null entries in variable-dimension columns, the
corresponding element of `entszs' should be set to zero.<BR>
</DL>
<DL><DT>
<B>
 `nlflgs'
</B><BR><BR>
<DD>
 is an array of boolean flags, each specifying whether the corresponding
column entry is null. For columns that don't allow null values, the
contents of this array are ignored. In all cases, `nlflgs' must have
dimension at least equal to the number of rows in the segment.<BR>
</DL>
   To add a double precision column to a segment, call <a href="../cspice/ekacld_c.html">ekacld_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekacld_c.html">ekacld_c</a> ( &lt;handle&gt;, &lt;segno&gt;,  &lt;column&gt;, &lt;dvals&gt;,   {Add d.p.
              &lt;entszs&gt;, &lt;nlflgs&gt;, &lt;rcptrs&gt;, wkindx  );  column}
</PRE>
   The arguments have the same meanings as the corresponding arguments of
   <a href="../cspice/ekaclc_c.html">ekaclc_c</a>, except that `dvals' represents a double precision array.
<P>
 
   Values of type TIME are also added using <a href="../cspice/ekacld_c.html">ekacld_c</a>. When a column
   contains TIME values (as indicated by its declared data type), the
   values are stored as ephemeris seconds past J2000 TDB. When starting
   with UTC or SCLK time values, the CSPICE conversion routines <a href="../cspice/str2et_c.html">str2et_c</a> or
   <a href="../cspice/scs2e_c.html">scs2e_c</a> may be used to obtain equivalent double precision TDB values.
   See the <a href="../req/time.html">TIME.REQ</a> or <a href="../req/sclk.html">SCLK.REQ</a> Required Reading for details.
<P>
 
   To add an integer column to a segment, call <a href="../cspice/ekacli_c.html">ekacli_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekacli_c.html">ekacli_c</a> ( &lt;handle&gt;, &lt;segno&gt;,  &lt;column&gt;, &lt;ivals&gt;,      {Add integer
              &lt;entszs&gt;, &lt;nlflgs&gt;, &lt;rcptrs&gt;, wkindx  );     column}
</PRE>
   The arguments have the same meanings as the corresponding arguments of
   <a href="../cspice/ekaclc_c.html">ekaclc_c</a>, except that `ivals' represents an integer array.
<P>
 
<BR><BR>
<A NAME="Completing a fast write"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Completing a fast write
</H3><P><BR><BR>
   Once all columns have been added to the segment, the fast write
   operation on the segment is completed using a call to <a href="../cspice/ekffld_c.html">ekffld_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekffld_c.html">ekffld_c</a> ( &lt;handle&gt;, &lt;segno&gt;, &lt;rcptrs&gt; )    {Finish fast write}
</PRE>
   The meanings of the arguments of <a href="../cspice/ekffld_c.html">ekffld_c</a> are identical to those of the
   same names belonging to <a href="../cspice/ekifld_c.html">ekifld_c</a>.
<P>
 
   Calling <a href="../cspice/ekffld_c.html">ekffld_c</a> is an essential step; the segment will not be
   structurally valid until this call has been made.
<P>
 
   Once the fast write operation has been completed, the segment may be
   modified using the record-oriented writers.
<P>
 
<BR><BR>
<A NAME="Restrictions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Restrictions
</H3><P><BR><BR>
   Creating a segment using the fast writer routines should be regarded as
   an ``indivisible'' process: other EK operations should not be performed
   when a fast write is in progress.
<P>
 
   Record-oriented append, insert, and delete operations are not supported
   for a segment in the process of being constructed by the fast writers.
   Updating or reading column entries in the middle of a fast write is also
   not supported.
<P>
 
   Fast write operations may not be interleaved with query-and-fetch
   operations: an application may not start a fast write, issue a query,
   then continue the fast write, or vice versa.
<P>
 
   Only one segment can be created at a time using the fast writers.
<P>
 
   One cannot extend an existing segment using the fast write functions.
   However, a segment created using the fast writers, once completed using
   a call to <a href="../cspice/ekffld_c.html">ekffld_c</a>, may be modified using the record-oriented write,
   update, or delete functions.
<P>
 
<BR><BR>
<A NAME="Updating an existing sequence EK"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Updating an existing sequence EK
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Except when a fast write is in progress, any segment of a sequence EK
   open for write access may be updated. Updates may consist of adding
   records, deleting records, or updating individual column entries.
<P>
 
   Adding records is done using the record-oriented writers, which are
   described above. Column entries may be updated using the functions
   <a href="../cspice/ekucec_c.html">ekucec_c</a>, <a href="../cspice/ekuced_c.html">ekuced_c</a>, and <a href="../cspice/ekucei_c.html">ekucei_c</a>, which operate on, respectively,
   character, double precision (or time), and integer column entries. The
   argument lists of these functions are identical to the record-oriented
   column entry addition functions of the corresponding data types.
<P>
 
   When updating a variable-size column entry, it is permissible to replace
   the original entry with one having a different size. Variable-length
   strings also can be replaced with strings of different lengths.
<P>
 
   For columns that allow null values, null entries can be updated with
   non-null values and vice versa.
<P>
 
   Records are deleted using a call to <a href="../cspice/ekdelr_c.html">ekdelr_c</a>:
<P>
 
<PRE>
   <a href="../cspice/ekdelr_c.html">ekdelr_c</a> ( &lt;handle&gt;, &lt;segno&gt;, &lt;recno&gt; );   {Delete record}
</PRE>
   With the arguments:
<P>
 
<DL><DT>
<B>
 `handle'
</B><BR><BR>
<DD>
 is the DAS file handle obtained from <a href="../cspice/ekopn_c.html">ekopn_c</a> or <a href="../cspice/ekopw_c.html">ekopw_c</a>.<BR>
</DL>
<DL><DT>
<B>
 `segno'
</B><BR><BR>
<DD>
 is the number of the segment containing the record of interest. `segno'
must be a segment number obtained from <a href="../cspice/ekbseg_c.html">ekbseg_c</a> or <a href="../cspice/ekifld_c.html">ekifld_c</a>.<BR>
</DL>
<DL><DT>
<B>
 `recno'
</B><BR><BR>
<DD>
 is the number of the record to delete.<BR>
</DL>
   Deleting all records from a segment simply leaves an empty segment in
   the parent sequence EK; segments cannot be deleted.
<P>
 
<BR><BR>
<A NAME="Closing a sequence EK"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Closing a sequence EK
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   When all segments in a sequence EK are complete, the sequence EK must be
   closed by calling <a href="../cspice/ekcls_c.html">ekcls_c</a>. This step is necessary to create a
   structurally correct sequence EK, since some written data may be
   buffered but not yet written to the physical sequence EK after the last
   segment has been completed. Also, <a href="../cspice/ekcls_c.html">ekcls_c</a> re-organizes (using the DAS
   subsystem) the physical records in the sequence EK to enhance read
   performance when the file is reopened.
<P>
 
   The record-oriented read routines may be used to read data from a
   sequence EK before it has been closed. However, a sequence EK open for
   write access may not by loaded by <a href="../cspice/furnsh_c.html">furnsh_c</a> and hence is not accessible
   by the sequence EK query and fetch routines.
<P>
 
<BR><BR>
<A NAME="Appendix A --- Summary of E-kernel Functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Appendix A --- Summary of E-kernel Functions
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<BR><BR>
<A NAME="Summary of mnemonics"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Summary of mnemonics
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   CSPICE contains a family of functions that are designed specifically for
   use with binary EK files. The name of each function begins with the
   letters ```ek','' followed by a two- or three-character mnemonic. For
   example, the function that issues a query and finds the matching rows is
   named <a href="../cspice/ekfind_c.html">ekfind_c</a>, pronounced ``E-K-FIND.''
<P>
 
   Many of the lower-level CSPICE functions have SPICELIB counterparts
   implemented in Fortran as entry points of another function.
<P>
 
   The following is a complete list of mnemonics and translations, in
   alphabetical order.
<P>
 
<PRE>
   Header files:
 
      SpiceEK.h
 
   CSPICE wrappers:
 
      <a href="../cspice/ekacec_c.html">ekacec_c</a>   ( EK, add character data to column           )
      <a href="../cspice/ekaced_c.html">ekaced_c</a>   ( EK, add d.p. data to column                )
      <a href="../cspice/ekacei_c.html">ekacei_c</a>   ( EK, add integer data to column             )
      <a href="../cspice/ekaclc_c.html">ekaclc_c</a>   ( EK, add character column to segment        )
      <a href="../cspice/ekacld_c.html">ekacld_c</a>   ( EK, add double precision column to segment )
      <a href="../cspice/ekacli_c.html">ekacli_c</a>   ( EK, add integer column to segment          )
      <a href="../cspice/ekappr_c.html">ekappr_c</a>   ( EK, append record onto segment             )
      <a href="../cspice/ekbseg_c.html">ekbseg_c</a>   ( EK, start new segment                      )
      <a href="../cspice/ekccnt_c.html">ekccnt_c</a>   ( EK, column count                           )
      <a href="../cspice/ekcii_c.html">ekcii_c</a>    ( EK, column info by index                   )
      <a href="../cspice/ekcls_c.html">ekcls_c</a>    ( EK, close file                             )
      <a href="../cspice/ekdelr_c.html">ekdelr_c</a>   ( EK, delete record from segment             )
      <a href="../cspice/ekffld_c.html">ekffld_c</a>   ( EK, finish fast write                      )
      <a href="../cspice/ekfind_c.html">ekfind_c</a>   ( EK, find data                              )
      <a href="../cspice/ekgc_c.html">ekgc_c</a>     ( EK, get event data, character              )
      <a href="../cspice/ekgd_c.html">ekgd_c</a>     ( EK, get event data, double precision       )
      <a href="../cspice/ekgi_c.html">ekgi_c</a>     ( EK, get event data, integer                )
      <a href="../cspice/ekifld_c.html">ekifld_c</a>   ( EK, initialize segment for fast write      )
      <a href="../cspice/ekinsr_c.html">ekinsr_c</a>   ( EK, insert record into segment             )
      <a href="../cspice/eklef_c.html">eklef_c</a>    ( EK, load event file                        )
      <a href="../cspice/eknelt_c.html">eknelt_c</a>   ( EK, get number of elements in column entry )
      <a href="../cspice/eknseg_c.html">eknseg_c</a>   ( EK, number of segments in file             )
      <a href="../cspice/ekntab_c.html">ekntab_c</a>   ( EK, return number of loaded tables         )
      <a href="../cspice/ekopn_c.html">ekopn_c</a>    ( EK, open new file                          )
      <a href="../cspice/ekopr_c.html">ekopr_c</a>    ( EK, open file for reading                  )
      <a href="../cspice/ekops_c.html">ekops_c</a>    ( EK, open scratch file                      )
      <a href="../cspice/ekopw_c.html">ekopw_c</a>    ( EK, open file for writing                  )
      <a href="../cspice/ekpsel_c.html">ekpsel_c</a>   ( EK, parse SELECT clause                    )
      <a href="../cspice/ekrcec_c.html">ekrcec_c</a>   ( EK, read column entry element, character   )
      <a href="../cspice/ekrced_c.html">ekrced_c</a>   ( EK, read column entry element, d.p.        )
      <a href="../cspice/ekrcei_c.html">ekrcei_c</a>   ( EK, read column entry element, integer     )
      <a href="../cspice/ekssum_c.html">ekssum_c</a>   ( EK, return segment summary                 )
      <a href="../cspice/ektnam_c.html">ektnam_c</a>   ( EK, return name of loaded table            )
      <a href="../cspice/ekucec_c.html">ekucec_c</a>   ( EK, update character column entry          )
      <a href="../cspice/ekuced_c.html">ekuced_c</a>   ( EK, update d.p column entry                )
      <a href="../cspice/ekucei_c.html">ekucei_c</a>   ( EK, update integer column entry            )
      <a href="../cspice/ekuef_c.html">ekuef_c</a>    ( EK, unload event file                      )
 
   Low-level routines converted by f2c:
 
      eksrch_    ( EK, search for events                      )
</PRE>
<BR><BR>
<A NAME="Summary of Calling Sequences"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Summary of Calling Sequences
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The calling sequences for the EK functions are summarized below. The
   functions are grouped by purpose.
<P>
 
   Load files for query access, unload files:
<P>
 
<PRE>
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( fname )
   <a href="../cspice/unload_c.html">unload_c</a> ( fname )
</PRE>
   Open files for record-oriented reading or writing, close files:
<P>
 
<PRE>
   dafllc_  ( &amp;handle )
   <a href="../cspice/ekcls_c.html">ekcls_c</a>  ( handle )
   <a href="../cspice/ekopn_c.html">ekopn_c</a>  ( fname, ifname, ncomch, &amp;handle )
   <a href="../cspice/ekopr_c.html">ekopr_c</a>  ( fname, &amp;handle )
   <a href="../cspice/ekops_c.html">ekops_c</a>  ( &amp;handle )
   <a href="../cspice/ekopw_c.html">ekopw_c</a>  ( fname, &amp;handle )
</PRE>
   Obtain summaries of sequence EK segments:
<P>
 
<PRE>
   <a href="../cspice/eknseg_c.html">eknseg_c</a> ( handle )
   <a href="../cspice/ekssum_c.html">ekssum_c</a> ( handle, segno, &amp;segsum )
</PRE>
   Obtain summaries of loaded tables:
<P>
 
<PRE>
   <a href="../cspice/ekccnt_c.html">ekccnt_c</a> ( table, &amp;ccount )
   <a href="../cspice/ekcii_c.html">ekcii_c</a>  ( table, cindex, lenout, column, &amp;attdsc )
   <a href="../cspice/ekntab_c.html">ekntab_c</a> ( &amp;n )
   <a href="../cspice/ektnam_c.html">ektnam_c</a> ( n, lenout, table )
</PRE>
   Query and fetch:
<P>
 
<PRE>
   <a href="../cspice/ekfind_c.html">ekfind_c</a> ( query,  lenout, &amp;nmrows, &amp;error, errmsg )
   <a href="../cspice/ekgc_c.html">ekgc_c</a>   ( selidx, row,    elment,  lenout, cdata, &amp;null,
              &amp;found                                         )
   <a href="../cspice/ekgd_c.html">ekgd_c</a>   ( selidx, row,    elment,  ddata, &amp;null,  &amp;found )
   <a href="../cspice/ekgi_c.html">ekgi_c</a>   ( selidx, row,    elment,  idata, &amp;null,  &amp;found )
   <a href="../cspice/eknelt_c.html">eknelt_c</a> ( selidx, row )
   <a href="../cspice/ekpsel_c.html">ekpsel_c</a> ( query,  msglen, tablen, collen, &amp;n,
              xbegs,  xends,  xtypes, xclass, tabs,
              cols,   &amp;error, errmsg                )
</PRE>
   Record-oriented read:
<P>
 
<PRE>
   <a href="../cspice/ekrcec_c.html">ekrcec_c</a> ( handle, segno,  recno, column, lenout, &amp;nvals,
              cvals   &amp;isnull                               )
   <a href="../cspice/ekrced_c.html">ekrced_c</a> ( handle, segno,  recno, column, &amp;nvals, dvals,
              &amp;isnull                                       )
   <a href="../cspice/ekrcei_c.html">ekrcei_c</a> ( handle, segno,  recno, column, &amp;nvals, ivals,
              &amp;isnull                                       )
</PRE>
   Fast write:
<P>
 
<PRE>
   <a href="../cspice/ekifld_c.html">ekifld_c</a> ( handle, tabnam, ncols,  nrows,  cnmlen, cnames,
              declen, decls,  &amp;segno, rcptrs                 )
   <a href="../cspice/ekaclc_c.html">ekaclc_c</a> ( handle, segno,  column, vallen, cvals,  entszs,
              nlflgs, rcptrs, wkindx                         )
   <a href="../cspice/ekacld_c.html">ekacld_c</a> ( handle, segno,  column, dvals,  entszs,
              nlflgs, rcptrs, wkindx                  )
   <a href="../cspice/ekacli_c.html">ekacli_c</a> ( handle, segno,  column, ivals,  entszs,
              nlflgs, rcptrs, wkindx                  )
   <a href="../cspice/ekffld_c.html">ekffld_c</a> ( handle, segno,  rcptrs )
 
</PRE>
   Begin segment for record-oriented write:
<P>
 
<PRE>
   <a href="../cspice/ekbseg_c.html">ekbseg_c</a> ( handle, tabnam, ncols, cnmlen, cnames, declen,
              decls,  &amp;segno                                )
</PRE>
   Insert, append, or delete records:
<P>
 
<PRE>
   <a href="../cspice/ekappr_c.html">ekappr_c</a> ( handle, segno,  &amp;recno )
   <a href="../cspice/ekdelr_c.html">ekdelr_c</a> ( handle, segno,  recno  )
   <a href="../cspice/ekinsr_c.html">ekinsr_c</a> ( handle, segno,  &amp;recno )
</PRE>
   Record-oriented write and update:
<P>
 
<PRE>
   <a href="../cspice/ekacec_c.html">ekacec_c</a> ( handle, segno,  recno, column, nvals, vallen,
              cvals,  isnull                               )
   <a href="../cspice/ekaced_c.html">ekaced_c</a> ( handle, segno,  recno, column, nvals,
              dvals,  isnull                       )
   <a href="../cspice/ekacei_c.html">ekacei_c</a> ( handle, segno,  recno, column, nvals,
              ivals,  isnull                       )
   <a href="../cspice/ekucec_c.html">ekucec_c</a> ( handle, segno,  recno, column, nvals, vallen,
              cvals,  isnull                               )
   <a href="../cspice/ekuced_c.html">ekuced_c</a> ( handle, segno,  recno, column, nvals,
              dvals,  isnull                       )
   <a href="../cspice/ekucei_c.html">ekucei_c</a> ( handle, segno,  recno, column, nvals,
              ivals,  isnull                       )
</PRE>
<BR><BR>
<A NAME="Revisions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Revisions
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
<BR><BR>
<A NAME="February 24, 2010 EDW (JPL)"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> February 24, 2010 EDW (JPL)
</H3><P><BR><BR>
   Documentation expanded to include descriptions of Icy functions.
<P>
 
<BR><BR>
<A NAME="April 1, 2009"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> April 1, 2009
</H3><P><BR><BR>
   Added a note about the SPICE file identification word for EK files.
<P>
 
<BR><BR>
<A NAME="Feb. 06, 2002"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Feb. 06, 2002
</H3><P><BR><BR>
   Several typos were corrected.
<P>
 
<BR><BR>
<A NAME="Jan. 15, 2002"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Jan. 15, 2002
</H3><P><BR><BR>
   Initial release.
<P>
 

</TD>
</TR>
</TBODY>
</TABLE>

</BODY>

</HTML>
